-
+
+
-
+
@@ -3041,10 +3276,9 @@
Conf
+
+ Back to top
+
@@ -3071,11 +3305,10 @@
Conf
-
-
+
-
+
diff --git a/objects.inv b/objects.inv
index 01fde93f2..35849246f 100644
Binary files a/objects.inv and b/objects.inv differ
diff --git a/search/search_index.json b/search/search_index.json
index 6f6de08af..348fa2f87 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"conf/","title":"Conf","text":"
Configuration file for the Sphinx documentation builder.
This file only contains a selection of the most common options. For a full list see the documentation: https://www.sphinx-doc.org/en/master/usage/configuration.html
-- Path setup --------------------------------------------------------------
In\u00a0[\u00a0]: Copied!
# If extensions (or modules to document with autodoc) are in another directory,\n# add these directories to sys.path here. If the directory is relative to the\n# documentation root, use os.path.abspath to make it absolute, like shown here.\n#\nimport os\nimport sys\n
# If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # import os import sys In\u00a0[\u00a0]: Copied!
os.environ['TRULENS_BACKEND'] = 'keras'\nsys.path.insert(0, os.path.abspath('.'))\nsys.path.insert(0, os.path.abspath('../'))\n os.environ['TRULENS_BACKEND'] = 'keras' sys.path.insert(0, os.path.abspath('.')) sys.path.insert(0, os.path.abspath('../'))
-- Project information -----------------------------------------------------
In\u00a0[\u00a0]: Copied!
project = 'trulens'\ncopyright = '2023, TruEra'\nauthor = 'TruEra'\n
project = 'trulens' copyright = '2023, TruEra' author = 'TruEra'
-- General configuration ---------------------------------------------------
In\u00a0[\u00a0]: Copied!
# Add any Sphinx extension module names here, as strings. They can be\n# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom\n# ones.\nextensions = [\n 'sphinx.ext.autodoc',\n 'sphinx.ext.napoleon',\n 'recommonmark',\n 'sphinx.ext.mathjax',\n]\n
# Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'recommonmark', 'sphinx.ext.mathjax', ]
napoleon_google_docstring = False napoleon_use_param = False napoleon_use_ivar = True
In\u00a0[\u00a0]: Copied!
def skip(app, what, name, obj, would_skip, options):\n if name == '__init__' or name == '__call__':\n return False\n return would_skip\n
def skip(app, what, name, obj, would_skip, options): if name == '__init__' or name == '__call__': return False return would_skip In\u00a0[\u00a0]: Copied!
def setup(app):\n app.connect('autodoc-skip-member', skip)\n def setup(app): app.connect('autodoc-skip-member', skip) In\u00a0[\u00a0]: Copied!
# Add any paths that contain templates here, relative to this directory.\ntemplates_path = ['_templates']\n
# Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] In\u00a0[\u00a0]: Copied!
# List of patterns, relative to source directory, that match files and\n# directories to ignore when looking for source files.\n# This pattern also affects html_static_path and html_extra_path.\nexclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']\n
# List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
-- Options for HTML output -------------------------------------------------
In\u00a0[\u00a0]: Copied!
# The theme to use for HTML and HTML Help pages. See the documentation for\n# a list of builtin themes.\n#\nhtml_theme = 'sphinx_rtd_theme'\n
# The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # html_theme = 'sphinx_rtd_theme' In\u00a0[\u00a0]: Copied!
# Add any paths that contain custom static files (such as style sheets) here,\n# relative to this directory. They are copied after the builtin static files,\n# so a file named \"default.css\" will overwrite the builtin \"default.css\".\nhtml_static_path = ['_static']\n
# Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named \"default.css\" will overwrite the builtin \"default.css\". html_static_path = ['_static'] In\u00a0[\u00a0]: Copied!
from recommonmark.parser import CommonMarkParser\n
from recommonmark.parser import CommonMarkParser In\u00a0[\u00a0]: Copied!
source_parsers = {'.md': CommonMarkParser}\n source_parsers = {'.md': CommonMarkParser} In\u00a0[\u00a0]: Copied!
source_suffix = ['.rst', '.md']\n
source_suffix = ['.rst', '.md']"},{"location":"welcome/","title":"Welcome to TruLens!","text":""},{"location":"welcome/#welcome-to-trulens","title":"\ud83e\udd91 Welcome to TruLens!","text":"
TruLens provides a set of tools for developing and monitoring neural nets, including large language models. This includes both tools for evaluation of LLMs and LLM-based applications with TruLens-Eval and deep learning explainability with TruLens-Explain. TruLens-Eval and TruLens-Explain are housed in separate packages and can be used independently.
The best way to support TruLens is to give us a \u2b50 and join our slack community!
"},{"location":"welcome/#trulens-eval","title":"TruLens-Eval","text":"
TruLens-Eval contains instrumentation and evaluation tools for large language model (LLM) based applications. It supports the iterative development and monitoring of a wide range of LLM applications by wrapping your application to log key metadata across the entire chain (or off chain if your project does not use chains) on your local machine. Importantly, it also gives you the tools you need to evaluate the quality of your LLM-based applications.
TruLens-Eval has two key value propositions:
- Evaluation:
- TruLens supports the the evaluation of inputs, outputs and internals of your LLM application using any model (including LLMs).
- A number of feedback functions for evaluation are implemented out-of-the-box such as groundedness, relevance and toxicity. The framework is also easily extensible for custom evaluation requirements.
- Tracking:
- TruLens contains instrumentation for any LLM application including question answering, retrieval-augmented generation, agent-based applications and more. This instrumentation allows for the tracking of a wide variety of usage metrics and metadata. Read more in the instrumentation overview.
- TruLens' instrumentation can be applied to any LLM application without being tied down to a given framework. Additionally, deep integrations with LangChain and Llama-Index allow the capture of internal metadata and text.
- Anything that is tracked by the instrumentation can be evaluated!
The process for building your evaluated and tracked LLM application with TruLens is shown below \ud83d\udc47
"},{"location":"welcome/#installation-and-setup","title":"Installation and setup","text":"
Install trulens-eval from PyPI.
pip install trulens-eval\n
"},{"location":"welcome/#quick-usage","title":"Quick Usage","text":"
TruLens supports the evaluation of tracking for any LLM app framework. Choose a framework below to get started:
Langchain
langchain_quickstart.ipynb.
Llama-Index
llama_index_quickstart.ipynb.
Custom Text to Text Apps
text2text_quickstart.ipynb.
"},{"location":"welcome/#trulens-explain","title":"TruLens-Explain","text":"
TruLens-Explain is a cross-framework library for deep learning explainability. It provides a uniform abstraction over a number of different frameworks. It provides a uniform abstraction layer over TensorFlow, Pytorch, and Keras and allows input and internal explanations.
"},{"location":"welcome/#installation-and-setup_1","title":"Installation and Setup","text":"
These installation instructions assume that you have conda installed and added to your path.
-
Create a virtual environment (or modify an existing one).
conda create -n \"<my_name>\" python=3 # Skip if using existing environment.\nconda activate <my_name>\n
-
Install dependencies.
conda install tensorflow-gpu=1 # Or whatever backend you're using.\nconda install keras # Or whatever backend you're using.\nconda install matplotlib # For visualizations.\n
-
[Pip installation] Install the trulens pip package from PyPI.
pip install trulens\n
"},{"location":"welcome/#quick-usage_1","title":"Quick Usage","text":"
To quickly play around with the TruLens library, check out the following Colab notebooks:
- PyTorch:
- TensorFlow 2 / Keras:
For more information, see TruLens-Explain Documentation.
"},{"location":"welcome2/","title":"Welcome2","text":""},{"location":"welcome2/#welcome-to-trulens","title":"\ud83e\udd91 Welcome to TruLens!","text":"
TruLens provides a set of tools for developing and monitoring neural nets, including large language models. This includes both tools for evaluation of LLMs and LLM-based applications with TruLens-Eval and deep learning explainability with TruLens-Explain. TruLens-Eval and TruLens-Explain are housed in separate packages and can be used independently.
The best way to support TruLens is to give us a \u2b50 and join our slack community!
"},{"location":"welcome2/#trulens-eval","title":"TruLens-Eval","text":"
TruLens-Eval contains instrumentation and evaluation tools for large language model (LLM) based applications. It supports the iterative development and monitoring of a wide range of LLM applications by wrapping your application to log key metadata across the entire chain (or off chain if your project does not use chains) on your local machine. Importantly, it also gives you the tools you need to evaluate the quality of your LLM-based applications.
TruLens-Eval has two key value propositions:
- Evaluation:
- TruLens supports the the evaluation of inputs, outputs and internals of your LLM application using any model (including LLMs).
- A number of feedback functions for evaluation are implemented out-of-the-box such as groundedness, relevance and toxicity. The framework is also easily extensible for custom evaluation requirements.
- Tracking:
- TruLens contains instrumentation for any LLM application including question answering, retrieval-augmented generation, agent-based applications and more. This instrumentation allows for the tracking of a wide variety of usage metrics and metadata. Read more in the instrumentation overview.
- TruLens' instrumentation can be applied to any LLM application without being tied down to a given framework. Additionally, deep integrations with LangChain and Llama-Index allow the capture of internal metadata and text.
- Anything that is tracked by the instrumentation can be evaluated!
The process for building your evaluated and tracked LLM application with TruLens is shown below \ud83d\udc47
"},{"location":"welcome2/#installation-and-setup","title":"Installation and setup","text":"
Install trulens-eval from PyPI.
pip install trulens-eval\n
"},{"location":"welcome2/#quick-usage","title":"Quick Usage","text":"
TruLens supports the evaluation of tracking for any LLM app framework. Choose a framework below to get started:
Langchain
langchain_quickstart.ipynb.
Llama-Index
llama_index_quickstart.ipynb.
Custom Text to Text Apps
text2text_quickstart.ipynb.
"},{"location":"welcome2/#trulens-explain","title":"TruLens-Explain","text":"
TruLens-Explain is a cross-framework library for deep learning explainability. It provides a uniform abstraction over a number of different frameworks. It provides a uniform abstraction layer over TensorFlow, Pytorch, and Keras and allows input and internal explanations.
"},{"location":"welcome2/#installation-and-setup_1","title":"Installation and Setup","text":"
These installation instructions assume that you have conda installed and added to your path.
-
Create a virtual environment (or modify an existing one).
conda create -n \"<my_name>\" python=3 # Skip if using existing environment.\nconda activate <my_name>\n
-
Install dependencies.
conda install tensorflow-gpu=1 # Or whatever backend you're using.\nconda install keras # Or whatever backend you're using.\nconda install matplotlib # For visualizations.\n
-
[Pip installation] Install the trulens pip package from PyPI.
pip install trulens\n
"},{"location":"welcome2/#quick-usage_1","title":"Quick Usage","text":"
To quickly play around with the TruLens library, check out the following Colab notebooks:
- PyTorch:
- TensorFlow 2 / Keras:
For more information, see TruLens-Explain Documentation.
"},{"location":"trulens_eval/CONTRIBUTING/","title":"Contributing to TruLens","text":"
Interested in contributing to TruLens? Here's how to get started!
"},{"location":"trulens_eval/CONTRIBUTING/#what-can-you-work-on","title":"What can you work on?","text":"
- \ud83d\udcaa Add new feedback functions
- \ud83e\udd1d Add new feedback function providers.
- \ud83d\udc1b Fix bugs
- \ud83c\udf89 Add usage examples
- \ud83e\uddea Add experimental features
- \ud83d\udcc4 Improve code quality & documentation
Also, join the AI Quality Slack community for ideas and discussions.
"},{"location":"trulens_eval/CONTRIBUTING/#add-new-feedback-functions","title":"\ud83d\udcaa Add new feedback functions","text":"
Feedback functions are the backbone of TruLens, and evaluating unique LLM apps may require new evaluations. We'd love your contribution to extend the feedback functions library so others can benefit!
- To add a feedback function for an existing model provider, you can add it to an existing provider module. You can read more about the structure of a feedback function in this guide.
- New methods can either take a single text (str) as a parameter or two different texts (str), such as prompt and retrieved context. It should return a float, or a dict of multiple floats. Each output value should be a float on the scale of 0 (worst) to 1 (best).
- Make sure to add its definition to this list.
"},{"location":"trulens_eval/CONTRIBUTING/#add-new-feedback-function-providers","title":"\ud83e\udd1d Add new feedback function providers.","text":"
Feedback functions often rely on a model provider, such as OpenAI or HuggingFace. If you need a new model provider to utilize feedback functions for your use case, we'd love if you added a new provider class, e.g. AzureOpenAI.
You can do so by creating a new provider module in this folder.
Alternatively, we also appreciate if you open a GitHub Issue if there's a model provider you need!
"},{"location":"trulens_eval/CONTRIBUTING/#fix-bugs","title":"\ud83d\udc1b Fix Bugs","text":"
Most bugs are reported and tracked in the Github Issues Page. We try our best in triaging and tagging these issues:
Issues tagged as bug are confirmed bugs. New contributors may want to start with issues tagged with good first issue. Please feel free to open an issue and/or assign an issue to yourself.
"},{"location":"trulens_eval/CONTRIBUTING/#add-usage-examples","title":"\ud83c\udf89 Add Usage Examples","text":"
If you have applied TruLens to track and evalaute a unique use-case, we would love your contribution in the form of an example notebook: e.g. Evaluating Pinecone Configuration Choices on Downstream App Performance
All example notebooks are expected to:
- Start with a title and description of the example
- Include a commented out list of dependencies and their versions, e.g.
# ! pip install trulens==0.10.0 langchain==0.0.268 - Include a linked button to a Google colab version of the notebook
- Add any additional requirements
"},{"location":"trulens_eval/CONTRIBUTING/#add-experimental-features","title":"\ud83e\uddea Add Experimental Features","text":"
If you have a crazy idea, make a PR for it! Whether if it's the latest research, or what you thought of in the shower, we'd love to see creative ways to improve TruLens.
"},{"location":"trulens_eval/CONTRIBUTING/#improve-code-quality-documentation","title":"\ud83d\udcc4 Improve Code Quality & Documentation","text":"
We would love your help in making the project cleaner, more robust, and more understandable. If you find something confusing, it most likely is for other people as well. Help us be better!
"},{"location":"trulens_eval/answer_relevance_smoke_tests/","title":"Answer Relevance","text":"In\u00a0[1]: Copied!
# Import relevance feedback function\nfrom trulens_eval.feedback import GroundTruthAgreement, OpenAI, LiteLLM\nfrom trulens_eval import TruBasicApp, Feedback, Tru, Select\nfrom test_cases import answer_relevance_golden_set\n\nTru().reset_database()\n
# Import relevance feedback function from trulens_eval.feedback import GroundTruthAgreement, OpenAI, LiteLLM from trulens_eval import TruBasicApp, Feedback, Tru, Select from test_cases import answer_relevance_golden_set Tru().reset_database()
\ud83e\udd91 Tru initialized with db url sqlite:///default.sqlite .\n\ud83d\uded1 Secret keys may be written to the database. See the `database_redact_keys` option of `Tru` to prevent this.\nDeleted 9 rows.\n
In\u00a0[2]: Copied!
import os\nos.environ[\"OPENAI_API_KEY\"] = \"...\"\nos.environ[\"COHERE_API_KEY\"] = \"...\"\nos.environ[\"HUGGINGFACE_API_KEY\"] = \"...\"\nos.environ[\"ANTHROPIC_API_KEY\"] = \"...\"\nos.environ[\"TOGETHERAI_API_KEY\"] = \"...\"\n
import os os.environ[\"OPENAI_API_KEY\"] = \"...\" os.environ[\"COHERE_API_KEY\"] = \"...\" os.environ[\"HUGGINGFACE_API_KEY\"] = \"...\" os.environ[\"ANTHROPIC_API_KEY\"] = \"...\" os.environ[\"TOGETHERAI_API_KEY\"] = \"...\" In\u00a0[3]: Copied!
# GPT 3.5\nturbo = OpenAI(model_engine=\"gpt-3.5-turbo\")\n\ndef wrapped_relevance_turbo(input, output):\n return turbo.relevance(input, output)\n\n# GPT 4\ngpt4 = OpenAI(model_engine=\"gpt-4\")\n\ndef wrapped_relevance_gpt4(input, output):\n return gpt4.relevance(input, output)\n\n# Cohere\ncommand_nightly = LiteLLM(model_engine=\"cohere/command-nightly\")\ndef wrapped_relevance_command_nightly(input, output):\n return command_nightly.relevance(input, output)\n\n# Anthropic\nclaude_1 = LiteLLM(model_engine=\"claude-instant-1\")\ndef wrapped_relevance_claude1(input, output):\n return claude_1.relevance(input, output)\n\nclaude_2 = LiteLLM(model_engine=\"claude-2\")\ndef wrapped_relevance_claude2(input, output):\n return claude_2.relevance(input, output)\n\n# Meta\nllama_2_13b = LiteLLM(model_engine=\"together_ai/togethercomputer/Llama-2-7B-32K-Instruct\")\ndef wrapped_relevance_llama2(input, output):\n return llama_2_13b.relevance(input, output)\n
# GPT 3.5 turbo = OpenAI(model_engine=\"gpt-3.5-turbo\") def wrapped_relevance_turbo(input, output): return turbo.relevance(input, output) # GPT 4 gpt4 = OpenAI(model_engine=\"gpt-4\") def wrapped_relevance_gpt4(input, output): return gpt4.relevance(input, output) # Cohere command_nightly = LiteLLM(model_engine=\"cohere/command-nightly\") def wrapped_relevance_command_nightly(input, output): return command_nightly.relevance(input, output) # Anthropic claude_1 = LiteLLM(model_engine=\"claude-instant-1\") def wrapped_relevance_claude1(input, output): return claude_1.relevance(input, output) claude_2 = LiteLLM(model_engine=\"claude-2\") def wrapped_relevance_claude2(input, output): return claude_2.relevance(input, output) # Meta llama_2_13b = LiteLLM(model_engine=\"together_ai/togethercomputer/Llama-2-7B-32K-Instruct\") def wrapped_relevance_llama2(input, output): return llama_2_13b.relevance(input, output)
Here we'll set up our golden set as a set of prompts, responses and expected scores stored in test_cases.py. Then, our numeric_difference method will look up the expected score for each prompt/response pair by exact match. After looking up the expected score, we will then take the L1 difference between the actual score and expected score.
In\u00a0[4]: Copied!
# Create a Feedback object using the numeric_difference method of the ground_truth object\nground_truth = GroundTruthAgreement(answer_relevance_golden_set)\n# Call the numeric_difference method with app and record and aggregate to get the mean absolute error\nf_mae = Feedback(ground_truth.mae, name = \"Mean Absolute Error\").on(Select.Record.calls[0].args.args[0]).on(Select.Record.calls[0].args.args[1]).on_output()\n
# Create a Feedback object using the numeric_difference method of the ground_truth object ground_truth = GroundTruthAgreement(answer_relevance_golden_set) # Call the numeric_difference method with app and record and aggregate to get the mean absolute error f_mae = Feedback(ground_truth.mae, name = \"Mean Absolute Error\").on(Select.Record.calls[0].args.args[0]).on(Select.Record.calls[0].args.args[1]).on_output()
\u2705 In Mean Absolute Error, input prompt will be set to __record__.calls[0].args.args[0] .\n\u2705 In Mean Absolute Error, input response will be set to __record__.calls[0].args.args[1] .\n\u2705 In Mean Absolute Error, input score will be set to __record__.main_output or `Select.RecordOutput` .\n
In\u00a0[5]: Copied!
tru_wrapped_relevance_turbo = TruBasicApp(wrapped_relevance_turbo, app_id = \"answer relevance gpt-3.5-turbo\", feedbacks=[f_mae])\n\ntru_wrapped_relevance_gpt4 = TruBasicApp(wrapped_relevance_gpt4, app_id = \"answer relevance gpt-4\", feedbacks=[f_mae])\n\ntru_wrapped_relevance_commandnightly = TruBasicApp(wrapped_relevance_command_nightly, app_id = \"answer relevance Command-Nightly\", feedbacks=[f_mae])\n\ntru_wrapped_relevance_claude1 = TruBasicApp(wrapped_relevance_claude1, app_id = \"answer relevance Claude 1\", feedbacks=[f_mae])\n\ntru_wrapped_relevance_claude2 = TruBasicApp(wrapped_relevance_claude2, app_id = \"answer relevance Claude 2\", feedbacks=[f_mae])\n\ntru_wrapped_relevance_llama2 = TruBasicApp(wrapped_relevance_llama2, app_id = \"answer relevance Llama-2-13b\", feedbacks=[f_mae])\n
tru_wrapped_relevance_turbo = TruBasicApp(wrapped_relevance_turbo, app_id = \"answer relevance gpt-3.5-turbo\", feedbacks=[f_mae]) tru_wrapped_relevance_gpt4 = TruBasicApp(wrapped_relevance_gpt4, app_id = \"answer relevance gpt-4\", feedbacks=[f_mae]) tru_wrapped_relevance_commandnightly = TruBasicApp(wrapped_relevance_command_nightly, app_id = \"answer relevance Command-Nightly\", feedbacks=[f_mae]) tru_wrapped_relevance_claude1 = TruBasicApp(wrapped_relevance_claude1, app_id = \"answer relevance Claude 1\", feedbacks=[f_mae]) tru_wrapped_relevance_claude2 = TruBasicApp(wrapped_relevance_claude2, app_id = \"answer relevance Claude 2\", feedbacks=[f_mae]) tru_wrapped_relevance_llama2 = TruBasicApp(wrapped_relevance_llama2, app_id = \"answer relevance Llama-2-13b\", feedbacks=[f_mae])
\u2705 added app answer relevance gpt-3.5-turbo\n\u2705 added feedback definition feedback_definition_hash_d2c7c6ef797c4fdbdcb802c0c74d451a\n\u2705 added app answer relevance with cot reasoning gpt-3.5-turbo\n\u2705 added feedback definition feedback_definition_hash_d2c7c6ef797c4fdbdcb802c0c74d451a\n\u2705 added app answer relevance gpt-4\n\u2705 added feedback definition feedback_definition_hash_d2c7c6ef797c4fdbdcb802c0c74d451a\n\u2705 added app answer relevance with cot reasoning gpt-4\n\u2705 added feedback definition feedback_definition_hash_d2c7c6ef797c4fdbdcb802c0c74d451a\n\u2705 added app answer relevance Command-Nightly\n\u2705 added feedback definition feedback_definition_hash_d2c7c6ef797c4fdbdcb802c0c74d451a\n\u2705 added app answer relevance Claude 1\n\u2705 added feedback definition feedback_definition_hash_d2c7c6ef797c4fdbdcb802c0c74d451a\n\u2705 added app answer relevance Claude 2\n\u2705 added feedback definition feedback_definition_hash_d2c7c6ef797c4fdbdcb802c0c74d451a\n\u2705 added app answer relevance Llama-2-13b\n\u2705 added feedback definition feedback_definition_hash_d2c7c6ef797c4fdbdcb802c0c74d451a\n
In\u00a0[\u00a0]: Copied!
for i in range(len(answer_relevance_golden_set)):\n prompt = answer_relevance_golden_set[i][\"query\"]\n response = answer_relevance_golden_set[i][\"response\"]\n \n with tru_wrapped_relevance_turbo as recording:\n tru_wrapped_relevance_turbo.app(prompt, response)\n \n with tru_wrapped_relevance_gpt4 as recording:\n tru_wrapped_relevance_gpt4.app(prompt, response)\n \n with tru_wrapped_relevance_commandnightly as recording:\n tru_wrapped_relevance_commandnightly.app(prompt, response)\n \n with tru_wrapped_relevance_claude1 as recording:\n tru_wrapped_relevance_claude1.app(prompt, response)\n\n with tru_wrapped_relevance_claude2 as recording:\n tru_wrapped_relevance_claude2.app(prompt, response)\n\n with tru_wrapped_relevance_llama2 as recording:\n tru_wrapped_relevance_llama2.app(prompt, response)\n
for i in range(len(answer_relevance_golden_set)): prompt = answer_relevance_golden_set[i][\"query\"] response = answer_relevance_golden_set[i][\"response\"] with tru_wrapped_relevance_turbo as recording: tru_wrapped_relevance_turbo.app(prompt, response) with tru_wrapped_relevance_gpt4 as recording: tru_wrapped_relevance_gpt4.app(prompt, response) with tru_wrapped_relevance_commandnightly as recording: tru_wrapped_relevance_commandnightly.app(prompt, response) with tru_wrapped_relevance_claude1 as recording: tru_wrapped_relevance_claude1.app(prompt, response) with tru_wrapped_relevance_claude2 as recording: tru_wrapped_relevance_claude2.app(prompt, response) with tru_wrapped_relevance_llama2 as recording: tru_wrapped_relevance_llama2.app(prompt, response) In\u00a0[12]: Copied!
Tru().get_leaderboard(app_ids=[]).sort_values(by='Mean Absolute Error')\n
Tru().get_leaderboard(app_ids=[]).sort_values(by='Mean Absolute Error') Out[12]: Mean Absolute Error latency total_cost app_id answer relevance gpt-3.5-turbo 0.172727 0.090909 0.000739 answer relevance gpt-4 0.245455 0.090909 0.014804 answer relevance Claude 1 0.250000 0.100000 0.000000 answer relevance Claude 2 0.300000 0.100000 0.000000 answer relevance Command-Nightly 0.300000 0.100000 0.000000 answer relevance Llama-2-13b 0.590000 0.100000 0.000000"},{"location":"trulens_eval/answer_relevance_smoke_tests/#answer-relevance-feedback-evaluation","title":"Answer Relevance Feedback Evaluation\u00b6","text":"
In many ways, feedbacks can be thought of as LLM apps themselves. Given text, they return some result. Thinking in this way, we can use TruLens to evaluate and track our feedback quality. We can even do this for different models (e.g. gpt-3.5 and gpt-4) or prompting schemes (such as chain-of-thought reasoning).
This notebook follows an evaluation of a set of test cases. You are encouraged to run this on your own and even expand the test cases to evaluate performance on test cases applicable to your scenario or domain.
"},{"location":"trulens_eval/basic_instrumentation/","title":"Overview","text":"In\u00a0[\u00a0]: Copied!
def custom_application(prompt: str) -> str:\n return \"a response\"\n
def custom_application(prompt: str) -> str: return \"a response\"
After creating the application, TruBasicApp allows you to instrument it in one line of code:
In\u00a0[\u00a0]: Copied!
from trulens_eval import TruBasicApp\nbasic_app_recorder = TruBasicApp(custom_application, app_id=\"Custom Application v1\")\n
from trulens_eval import TruBasicApp basic_app_recorder = TruBasicApp(custom_application, app_id=\"Custom Application v1\")
Then, you can operate the application like normal:
In\u00a0[\u00a0]: Copied!
with basic_app_recorder as recording:\n basic_app_recorder.app(\"What is the phone number for HR?\")\n
with basic_app_recorder as recording: basic_app_recorder.app(\"What is the phone number for HR?\")
Read more about TruBasicApp in the API reference or check out the text2text quickstart.
If instead, you're looking to use TruLens with a more complex custom application, you can use TruCustom.
For more information, plese read more about TruCustom in the API Reference
"},{"location":"trulens_eval/basic_instrumentation/#overview","title":"Overview\u00b6","text":"
TruLens provides a number of different instrumentation frameworks to allow you to inspect and evaluate the internals of your application and its associated records. In any framework you can track a wide variety of usage metrics and metadata, detailed below, along with the inputs and outputs of the application. For frameworks with deep integrations, TruLens can expose additional internals of the application for tracking.
"},{"location":"trulens_eval/basic_instrumentation/#what-can-you-track","title":"What can you track?\u00b6","text":""},{"location":"trulens_eval/basic_instrumentation/#usage-metrics","title":"Usage Metrics\u00b6","text":"
- Number of requests (n_requests)
- Number of successful ones (n_successful_requests)
- Number of class scores retrieved (n_classes)
- Total tokens processed (n_tokens)
- In streaming mode, number of chunks produced (n_stream_chunks)
- Number of prompt tokens supplied (n_prompt_tokens)
- Number of completion tokens generated (n_completion_tokens)
- Cost in USD (cost)
"},{"location":"trulens_eval/basic_instrumentation/#app-metadata","title":"App Metadata\u00b6","text":"
- App ID (app_id) - user supplied string or automatically generated hash
- Tags (tags) - user supplied string
- Model metadata - user supplied json
"},{"location":"trulens_eval/basic_instrumentation/#record-metadata","title":"Record Metadata\u00b6","text":"
- Record ID (record_id) - automatically generated, track individual application calls
- Timestamp (ts) - automatcially tracked, the timestamp of the application call
- Latency (latency) - the difference between the application call start and end time.
"},{"location":"trulens_eval/basic_instrumentation/#tracking-custom-applications","title":"Tracking custom applications\u00b6","text":"
Outside of integrations, TruLens supports the instrumentation of any text-to-text application, including custom ones.
The way to track this type of application is through TruBasicApp.
Suppose you have a generic text-to-text application as follows:
"},{"location":"trulens_eval/colab_dependencies/","title":"Colab dependencies","text":"In\u00a0[\u00a0]: Copied!
!pip install -U trulens-eval\n\n# Google Colab Dependencies\n!npm install localtunnel -q\n!pip install -q streamlit>=1.26.0\n
!pip install -U trulens-eval # Google Colab Dependencies !npm install localtunnel -q !pip install -q streamlit>=1.26.0"},{"location":"trulens_eval/context_relevance_smoke_tests/","title":"Context Relevance","text":"In\u00a0[1]: Copied!
# Import relevance feedback function\nfrom trulens_eval.feedback import GroundTruthAgreement, OpenAI, LiteLLM\nfrom trulens_eval import TruBasicApp, Feedback, Tru, Select\nfrom test_cases import context_relevance_golden_set\n\nimport openai\n\nTru().reset_database()\n
# Import relevance feedback function from trulens_eval.feedback import GroundTruthAgreement, OpenAI, LiteLLM from trulens_eval import TruBasicApp, Feedback, Tru, Select from test_cases import context_relevance_golden_set import openai Tru().reset_database()
\ud83e\udd91 Tru initialized with db url sqlite:///default.sqlite .\n\ud83d\uded1 Secret keys may be written to the database. See the `database_redact_keys` option of `Tru` to prevent this.\nDeleted 17 rows.\n
In\u00a0[2]: Copied!
import os\nos.environ[\"OPENAI_API_KEY\"] = \"...\"\nos.environ[\"COHERE_API_KEY\"] = \"...\"\nos.environ[\"HUGGINGFACE_API_KEY\"] = \"...\"\nos.environ[\"ANTHROPIC_API_KEY\"] = \"...\"\nos.environ[\"TOGETHERAI_API_KEY\"] = \"...\"\n
import os os.environ[\"OPENAI_API_KEY\"] = \"...\" os.environ[\"COHERE_API_KEY\"] = \"...\" os.environ[\"HUGGINGFACE_API_KEY\"] = \"...\" os.environ[\"ANTHROPIC_API_KEY\"] = \"...\" os.environ[\"TOGETHERAI_API_KEY\"] = \"...\" In\u00a0[3]: Copied!
# GPT 3.5\nturbo = OpenAI(model_engine=\"gpt-3.5-turbo\")\n\ndef wrapped_relevance_turbo(input, output):\n return turbo.qs_relevance(input, output)\n\n# GPT 4\ngpt4 = OpenAI(model_engine=\"gpt-4\")\n\ndef wrapped_relevance_gpt4(input, output):\n return gpt4.qs_relevance(input, output)\n\n# Cohere\ncommand_nightly = LiteLLM(model_engine=\"command-nightly\")\ndef wrapped_relevance_command_nightly(input, output):\n return command_nightly.qs_relevance(input, output)\n\n# Anthropic\nclaude_1 = LiteLLM(model_engine=\"claude-instant-1\")\ndef wrapped_relevance_claude1(input, output):\n return claude_1.qs_relevance(input, output)\n\nclaude_2 = LiteLLM(model_engine=\"claude-2\")\ndef wrapped_relevance_claude2(input, output):\n return claude_2.qs_relevance(input, output)\n\n# Meta\nllama_2_13b = LiteLLM(model_engine=\"together_ai/togethercomputer/Llama-2-7B-32K-Instruct\")\ndef wrapped_relevance_llama2(input, output):\n return llama_2_13b.qs_relevance(input, output)\n
# GPT 3.5 turbo = OpenAI(model_engine=\"gpt-3.5-turbo\") def wrapped_relevance_turbo(input, output): return turbo.qs_relevance(input, output) # GPT 4 gpt4 = OpenAI(model_engine=\"gpt-4\") def wrapped_relevance_gpt4(input, output): return gpt4.qs_relevance(input, output) # Cohere command_nightly = LiteLLM(model_engine=\"command-nightly\") def wrapped_relevance_command_nightly(input, output): return command_nightly.qs_relevance(input, output) # Anthropic claude_1 = LiteLLM(model_engine=\"claude-instant-1\") def wrapped_relevance_claude1(input, output): return claude_1.qs_relevance(input, output) claude_2 = LiteLLM(model_engine=\"claude-2\") def wrapped_relevance_claude2(input, output): return claude_2.qs_relevance(input, output) # Meta llama_2_13b = LiteLLM(model_engine=\"together_ai/togethercomputer/Llama-2-7B-32K-Instruct\") def wrapped_relevance_llama2(input, output): return llama_2_13b.qs_relevance(input, output)
Here we'll set up our golden set as a set of prompts, responses and expected scores stored in test_cases.py. Then, our numeric_difference method will look up the expected score for each prompt/response pair by exact match. After looking up the expected score, we will then take the L1 difference between the actual score and expected score.
In\u00a0[4]: Copied!
# Create a Feedback object using the numeric_difference method of the ground_truth object\nground_truth = GroundTruthAgreement(context_relevance_golden_set)\n# Call the numeric_difference method with app and record and aggregate to get the mean absolute error\nf_mae = Feedback(ground_truth.mae, name = \"Mean Absolute Error\").on(Select.Record.calls[0].args.args[0]).on(Select.Record.calls[0].args.args[1]).on_output()\n
# Create a Feedback object using the numeric_difference method of the ground_truth object ground_truth = GroundTruthAgreement(context_relevance_golden_set) # Call the numeric_difference method with app and record and aggregate to get the mean absolute error f_mae = Feedback(ground_truth.mae, name = \"Mean Absolute Error\").on(Select.Record.calls[0].args.args[0]).on(Select.Record.calls[0].args.args[1]).on_output()
\u2705 In Mean Absolute Error, input prompt will be set to __record__.calls[0].args.args[0] .\n\u2705 In Mean Absolute Error, input response will be set to __record__.calls[0].args.args[1] .\n\u2705 In Mean Absolute Error, input score will be set to __record__.main_output or `Select.RecordOutput` .\n
In\u00a0[5]: Copied!
tru_wrapped_relevance_turbo = TruBasicApp(wrapped_relevance_turbo, app_id = \"context relevance gpt-3.5-turbo\", feedbacks=[f_mae])\n\ntru_wrapped_relevance_gpt4 = TruBasicApp(wrapped_relevance_gpt4, app_id = \"context relevance gpt-4\", feedbacks=[f_mae])\n\ntru_wrapped_relevance_commandnightly = TruBasicApp(wrapped_relevance_command_nightly, app_id = \"context relevance Command-Nightly\", feedbacks=[f_mae])\n\ntru_wrapped_relevance_claude1 = TruBasicApp(wrapped_relevance_claude1, app_id = \"context relevance Claude 1\", feedbacks=[f_mae])\n\ntru_wrapped_relevance_claude2 = TruBasicApp(wrapped_relevance_claude2, app_id = \"context relevance Claude 2\", feedbacks=[f_mae])\n\ntru_wrapped_relevance_llama2 = TruBasicApp(wrapped_relevance_llama2, app_id = \"context relevance Llama-2-13b\", feedbacks=[f_mae])\n
tru_wrapped_relevance_turbo = TruBasicApp(wrapped_relevance_turbo, app_id = \"context relevance gpt-3.5-turbo\", feedbacks=[f_mae]) tru_wrapped_relevance_gpt4 = TruBasicApp(wrapped_relevance_gpt4, app_id = \"context relevance gpt-4\", feedbacks=[f_mae]) tru_wrapped_relevance_commandnightly = TruBasicApp(wrapped_relevance_command_nightly, app_id = \"context relevance Command-Nightly\", feedbacks=[f_mae]) tru_wrapped_relevance_claude1 = TruBasicApp(wrapped_relevance_claude1, app_id = \"context relevance Claude 1\", feedbacks=[f_mae]) tru_wrapped_relevance_claude2 = TruBasicApp(wrapped_relevance_claude2, app_id = \"context relevance Claude 2\", feedbacks=[f_mae]) tru_wrapped_relevance_llama2 = TruBasicApp(wrapped_relevance_llama2, app_id = \"context relevance Llama-2-13b\", feedbacks=[f_mae])
\u2705 added app context relevance gpt-3.5-turbo\n\u2705 added feedback definition feedback_definition_hash_ac1d5b3a2009be5efdb59a1f22e23053\n\u2705 added app context relevance gpt-4\n\u2705 added feedback definition feedback_definition_hash_ac1d5b3a2009be5efdb59a1f22e23053\n\u2705 added app context relevance Command-Nightly\n\u2705 added feedback definition feedback_definition_hash_ac1d5b3a2009be5efdb59a1f22e23053\n\u2705 added app context relevance Claude 1\n\u2705 added feedback definition feedback_definition_hash_ac1d5b3a2009be5efdb59a1f22e23053\n\u2705 added app context relevance Claude 2\n\u2705 added feedback definition feedback_definition_hash_ac1d5b3a2009be5efdb59a1f22e23053\n\u2705 added app context relevance Llama-2-13b\n\u2705 added feedback definition feedback_definition_hash_ac1d5b3a2009be5efdb59a1f22e23053\n
In\u00a0[\u00a0]: Copied!
for i in range(len(context_relevance_golden_set)):\n prompt = context_relevance_golden_set[i][\"query\"]\n response = context_relevance_golden_set[i][\"response\"]\n with tru_wrapped_relevance_turbo as recording:\n tru_wrapped_relevance_turbo.app(prompt, response)\n \n with tru_wrapped_relevance_gpt4 as recording:\n tru_wrapped_relevance_gpt4.app(prompt, response)\n \n with tru_wrapped_relevance_commandnightly as recording:\n tru_wrapped_relevance_commandnightly.app(prompt, response)\n \n with tru_wrapped_relevance_claude1 as recording:\n tru_wrapped_relevance_claude1.app(prompt, response)\n\n with tru_wrapped_relevance_claude2 as recording:\n tru_wrapped_relevance_claude2.app(prompt, response)\n\n with tru_wrapped_relevance_llama2 as recording:\n tru_wrapped_relevance_llama2.app(prompt, response)\n
for i in range(len(context_relevance_golden_set)): prompt = context_relevance_golden_set[i][\"query\"] response = context_relevance_golden_set[i][\"response\"] with tru_wrapped_relevance_turbo as recording: tru_wrapped_relevance_turbo.app(prompt, response) with tru_wrapped_relevance_gpt4 as recording: tru_wrapped_relevance_gpt4.app(prompt, response) with tru_wrapped_relevance_commandnightly as recording: tru_wrapped_relevance_commandnightly.app(prompt, response) with tru_wrapped_relevance_claude1 as recording: tru_wrapped_relevance_claude1.app(prompt, response) with tru_wrapped_relevance_claude2 as recording: tru_wrapped_relevance_claude2.app(prompt, response) with tru_wrapped_relevance_llama2 as recording: tru_wrapped_relevance_llama2.app(prompt, response) In\u00a0[7]: Copied!
Tru().get_leaderboard(app_ids=[]).sort_values(by=\"Mean Absolute Error\")\n
Tru().get_leaderboard(app_ids=[]).sort_values(by=\"Mean Absolute Error\")
\u2705 feedback result Mean Absolute Error DONE feedback_result_hash_086ffca9b39fe36e86797171e56e3f50\n
Out[7]: Mean Absolute Error latency total_cost app_id context relevance Claude 1 0.186667 0.066667 0.000000 context relevance gpt-3.5-turbo 0.206667 0.066667 0.000762 context relevance gpt-4 0.253333 0.066667 0.015268 context relevance Command-Nightly 0.313333 0.066667 0.000000 context relevance Claude 2 0.366667 0.066667 0.000000 context relevance Llama-2-13b 0.586667 0.066667 0.000000"},{"location":"trulens_eval/context_relevance_smoke_tests/#context-relevance-evaluations","title":"Context Relevance Evaluations\u00b6","text":"
In many ways, feedbacks can be thought of as LLM apps themselves. Given text, they return some result. Thinking in this way, we can use TruLens to evaluate and track our feedback quality. We can even do this for different models (e.g. gpt-3.5 and gpt-4) or prompting schemes (such as chain-of-thought reasoning).
This notebook follows an evaluation of a set of test cases. You are encouraged to run this on your own and even expand the test cases to evaluate performance on test cases applicable to your scenario or domain.
"},{"location":"trulens_eval/custom_feedback_functions/","title":"Custom Functions","text":"In\u00a0[\u00a0]: Copied!
from trulens_eval import Provider, Feedback, Select, Tru\n\nclass StandAlone(Provider):\n def custom_feedback(self, my_text_field: str) -> float:\n \"\"\"\n A dummy function of text inputs to float outputs.\n\n Parameters:\n my_text_field (str): Text to evaluate.\n\n Returns:\n float: square length of the text\n \"\"\"\n return 1.0 / (1.0 + len(my_text_field) * len(my_text_field))\n
from trulens_eval import Provider, Feedback, Select, Tru class StandAlone(Provider): def custom_feedback(self, my_text_field: str) -> float: \"\"\" A dummy function of text inputs to float outputs. Parameters: my_text_field (str): Text to evaluate. Returns: float: square length of the text \"\"\" return 1.0 / (1.0 + len(my_text_field) * len(my_text_field))
- Instantiate your provider and feedback functions. The feedback function is wrapped by the trulens-eval Feedback class which helps specify what will get sent to your function parameters (For example: Select.RecordInput or Select.RecordOutput)
In\u00a0[\u00a0]: Copied!
standalone = StandAlone()\nf_custom_function = Feedback(standalone.custom_feedback).on(\n my_text_field=Select.RecordOutput\n)\n
standalone = StandAlone() f_custom_function = Feedback(standalone.custom_feedback).on( my_text_field=Select.RecordOutput )
- Your feedback function is now ready to use just like the out of the box feedback functions. Below is an example of it being used.
In\u00a0[\u00a0]: Copied!
tru = Tru()\nfeedback_results = tru.run_feedback_functions(\n record=record,\n feedback_functions=[f_custom_function]\n)\ntru.add_feedbacks(feedback_results)\n
tru = Tru() feedback_results = tru.run_feedback_functions( record=record, feedback_functions=[f_custom_function] ) tru.add_feedbacks(feedback_results) In\u00a0[\u00a0]: Copied!
multi_output_feedback = Feedback(lambda input_param: {'output_key1': 0.1, 'output_key2': 0.9}, name=\"multi\").on(\n input_param=Select.RecordOutput\n)\nfeedback_results = tru.run_feedback_functions(\n record=record,\n feedback_functions=[multi_output_feedback]\n)\ntru.add_feedbacks(feedback_results)\n multi_output_feedback = Feedback(lambda input_param: {'output_key1': 0.1, 'output_key2': 0.9}, name=\"multi\").on( input_param=Select.RecordOutput ) feedback_results = tru.run_feedback_functions( record=record, feedback_functions=[multi_output_feedback] ) tru.add_feedbacks(feedback_results) In\u00a0[\u00a0]: Copied!
# Aggregators will run on the same dict keys.\nimport numpy as np\nmulti_output_feedback = Feedback(lambda input_param: {'output_key1': 0.1, 'output_key2': 0.9}, name=\"multi-agg\").on(\n input_param=Select.RecordOutput\n).aggregate(np.mean)\nfeedback_results = tru.run_feedback_functions(\n record=record,\n feedback_functions=[multi_output_feedback]\n)\ntru.add_feedbacks(feedback_results)\n # Aggregators will run on the same dict keys. import numpy as np multi_output_feedback = Feedback(lambda input_param: {'output_key1': 0.1, 'output_key2': 0.9}, name=\"multi-agg\").on( input_param=Select.RecordOutput ).aggregate(np.mean) feedback_results = tru.run_feedback_functions( record=record, feedback_functions=[multi_output_feedback] ) tru.add_feedbacks(feedback_results) In\u00a0[\u00a0]: Copied!
# For multi-context chunking, an aggregator can operate on a list of multi output dictionaries.\ndef dict_aggregator(list_dict_input):\n agg = 0\n for dict_input in list_dict_input:\n agg += dict_input['output_key1']\n return agg\nmulti_output_feedback = Feedback(lambda input_param: {'output_key1': 0.1, 'output_key2': 0.9}, name=\"multi-agg-dict\").on(\n input_param=Select.RecordOutput\n).aggregate(dict_aggregator)\nfeedback_results = tru.run_feedback_functions(\n record=record,\n feedback_functions=[multi_output_feedback]\n)\ntru.add_feedbacks(feedback_results)\n # For multi-context chunking, an aggregator can operate on a list of multi output dictionaries. def dict_aggregator(list_dict_input): agg = 0 for dict_input in list_dict_input: agg += dict_input['output_key1'] return agg multi_output_feedback = Feedback(lambda input_param: {'output_key1': 0.1, 'output_key2': 0.9}, name=\"multi-agg-dict\").on( input_param=Select.RecordOutput ).aggregate(dict_aggregator) feedback_results = tru.run_feedback_functions( record=record, feedback_functions=[multi_output_feedback] ) tru.add_feedbacks(feedback_results)"},{"location":"trulens_eval/custom_feedback_functions/#custom-functions","title":"Custom Functions\u00b6","text":"
Feedback functions are an extensible framework for evaluating LLMs. You can add your own feedback functions to evaluate the qualities required by your application by updating trulens_eval/feedback.py, or simply creating a new provider class and feedback function in youre notebook. If your contributions would be useful for others, we encourage you to contribute to TruLens!
Feedback functions are organized by model provider into Provider classes.
The process for adding new feedback functions is:
- Create a new Provider class or locate an existing one that applies to your feedback function. If your feedback function does not rely on a model provider, you can create a standalone class. Add the new feedback function method to your selected class. Your new method can either take a single text (str) as a parameter or both prompt (str) and response (str). It should return a float between 0 (worst) and 1 (best).
"},{"location":"trulens_eval/custom_feedback_functions/#multi-output-feedback-functions","title":"Multi-Output Feedback functions\u00b6","text":"
Trulens also supports multi-output feedback functions. As a typical feedback function will output a float between 0 and 1, multi-output should output a dictionary of output_key to a float between 0 and 1. The feedbacks table will display the feedback with column feedback_name:::outputkey
"},{"location":"trulens_eval/feedback_function_guide/","title":"Feedback Functions","text":"
The Feedback class contains the starting point for feedback function specification and evaluation. A typical use-case looks like this:
from trulens_eval import feedback, Select, Feedback\n\nhugs = feedback.Huggingface()\n\nf_lang_match = Feedback(hugs.language_match)\n .on_input_output()\n
The components of this specifications are:
-
Provider classes -- feedback.OpenAI contains feedback function implementations like qs_relevance. Other classes subtyping feedback.Provider include Huggingface and Cohere.
-
Feedback implementations -- openai.qs_relevance is a feedback function implementation. Feedback implementations are simple callables that can be run on any arguments matching their signatures. In the example, the implementation has the following signature:
def language_match(self, text1: str, text2: str) -> float:\n
That is, language_match is a plain python method that accepts two pieces of text, both strings, and produces a float (assumed to be between 0.0 and 1.0).
-
Feedback constructor -- The line Feedback(openai.language_match) constructs a Feedback object with a feedback implementation.
-
Argument specification -- The next line, on_input_output, specifies how the language_match arguments are to be determined from an app record or app definition. The general form of this specification is done using on but several shorthands are provided. on_input_output states that the first two argument to language_match (text1 and text2) are to be the main app input and the main output, respectively.
Several utility methods starting with .on provide shorthands:
- `on_input(arg) == on_prompt(arg: Optional[str])` -- both specify that the next\nunspecified argument or `arg` should be the main app input.\n\n- `on_output(arg) == on_response(arg: Optional[str])` -- specify that the next\nargument or `arg` should be the main app output.\n\n- `on_input_output() == on_input().on_output()` -- specifies that the first\ntwo arguments of implementation should be the main app input and main app\noutput, respectively.\n\n- `on_default()` -- depending on signature of implementation uses either\n`on_output()` if it has a single argument, or `on_input_output` if it has\ntwo arguments.\n\nSome wrappers include additional shorthands:\n\n### llama_index-specific selectors\n\n- `TruLlama.select_source_nodes()` -- outputs the selector of the source\n documents part of the engine output.\n
"},{"location":"trulens_eval/feedback_function_guide/#fine-grained-selection-and-aggregation","title":"Fine-grained Selection and Aggregation","text":"
For more advanced control on the feedback function operation, we allow data selection and aggregation. Consider this feedback example:
f_qs_relevance = Feedback(openai.qs_relevance)\n .on_input()\n .on(Select.Record.app.combine_docs_chain._call.args.inputs.input_documents[:].page_content)\n .aggregate(numpy.min)\n\n# Implementation signature:\n# def qs_relevance(self, question: str, statement: str) -> float:\n
-
Argument Selection specification -- Where we previously set, on_input_output , the on(Select...) line enables specification of where the statement argument to the implementation comes from. The form of the specification will be discussed in further details in the Specifying Arguments section.
-
Aggregation specification -- The last line aggregate(numpy.min) specifies how feedback outputs are to be aggregated. This only applies to cases where the argument specification names more than one value for an input. The second specification, for statement was of this type. The input to aggregate must be a method which can be imported globally. This requirement is further elaborated in the next section. This function is called on the float results of feedback function evaluations to produce a single float. The default is numpy.mean.
The result of these lines is that f_qs_relevance can be now be run on app/records and will automatically select the specified components of those apps/records:
record: Record = ...\napp: App = ...\n\nfeedback_result: FeedbackResult = f_qs_relevance.run(app=app, record=record)\n
The object can also be provided to an app wrapper for automatic evaluation:
app: App = tru.Chain(...., feedbacks=[f_qs_relevance])\n
"},{"location":"trulens_eval/feedback_function_guide/#specifying-implementation-function-and-aggregate","title":"Specifying Implementation Function and Aggregate","text":"
The function or method provided to the Feedback constructor is the implementation of the feedback function which does the actual work of producing a float indicating some quantity of interest.
Note regarding FeedbackMode.DEFERRED -- Any function or method (not static or class methods presently supported) can be provided here but there are additional requirements if your app uses the \"deferred\" feedback evaluation mode (when feedback_mode=FeedbackMode.DEFERRED are specified to app constructor). In those cases the callables must be functions or methods that are importable (see the next section for details). The function/method performing the aggregation has the same requirements.
"},{"location":"trulens_eval/feedback_function_guide/#import-requirement-deferred-feedback-mode-only","title":"Import requirement (DEFERRED feedback mode only)","text":"
If using deferred evaluation, the feedback function implementations and aggregation implementations must be functions or methods from a Provider subclass that is importable. That is, the callables must be accessible were you to evaluate this code:
from somepackage.[...] import someproviderclass\nfrom somepackage.[...] import somefunction\n\n# [...] means optionally further package specifications\n\nprovider = someproviderclass(...) # constructor arguments can be included\nfeedback_implementation1 = provider.somemethod\nfeedback_implementation2 = somefunction\n
For provided feedback functions, somepackage is trulens_eval.feedback and someproviderclass is OpenAI or one of the other Provider subclasses. Custom feedback functions likewise need to be importable functions or methods of a provider subclass that can be imported. Critically, functions or classes defined locally in a notebook will not be importable this way.
"},{"location":"trulens_eval/feedback_function_guide/#specifying-arguments","title":"Specifying Arguments","text":"
The mapping between app/records to feedback implementation arguments is specified by the on... methods of the Feedback objects. The general form is:
feedback: Feedback = feedback.on(argname1=selector1, argname2=selector2, ...)\n
That is, Feedback.on(...) returns a new Feedback object with additional argument mappings, the source of argname1 is selector1 and so on for further argument names. The types of selector1 is JSONPath which we elaborate on in the \"Selector Details\".
If argument names are ommitted, they are taken from the feedback function implementation signature in order. That is,
Feedback(...).on(argname1=selector1, argname2=selector2)\n
and
Feedback(...).on(selector1, selector2)\n
are equivalent assuming the feedback implementation has two arguments, argname1 and argname2, in that order.
"},{"location":"trulens_eval/feedback_function_guide/#running-feedback","title":"Running Feedback","text":"
Feedback implementations are simple callables that can be run on any arguments matching their signatures. However, once wrapped with Feedback, they are meant to be run on outputs of app evaluation (the \"Records\"). Specifically, Feedback.run has this definition:
def run(self, \n app: Union[AppDefinition, JSON], \n record: Record\n) -> FeedbackResult:\n
That is, the context of a Feedback evaluation is an app (either as AppDefinition or a JSON-like object) and a Record of the execution of the aforementioned app. Both objects are indexable using \"Selectors\". By indexable here we mean that their internal components can be specified by a Selector and subsequently that internal component can be extracted using that selector. Selectors for Feedback start by specifying whether they are indexing into an App or a Record via the __app__ and __record__ special attributes (see Selectors section below).
"},{"location":"trulens_eval/feedback_function_guide/#selector-details","title":"Selector Details","text":"
Apps and Records will be converted to JSON-like structures representing their callstack.
Selectors are of type JSONPath defined in utils/serial.py help specify paths into JSON-like structures (enumerating Record or App contents).
In most cases, the Select object produces only a single item but can also address multiple items.
You can access the JSON structure with with_record methods and then calling layout_calls_as_app.
for example
response = my_llm_app(query)\n\nfrom trulens_eval import TruChain\ntru_recorder = TruChain(\n my_llm_app,\n app_id='Chain1_ChatApplication')\n\nresponse, tru_record = tru_recorder.with_record(my_llm_app, query)\njson_like = tru_record.layout_calls_as_app()\n
If a selector looks like the below
Select.Record.app.combine_documents_chain._call\n
It can be accessed via the JSON-like via
json_like['app']['combine_documents_chain']['_call']\n
The top level record also contains these helper accessors
-
RecordInput = Record.main_input -- points to the main input part of a Record. This is the first argument to the root method of an app (for langchain Chains this is the __call__ method).
-
RecordOutput = Record.main_output -- points to the main output part of a Record. This is the output of the root method of an app (i.e. __call__ for langchain Chains).
-
RecordCalls = Record.app -- points to the root of the app-structured mirror of calls in a record. See App-organized Calls Section above.
"},{"location":"trulens_eval/feedback_function_guide/#multiple-inputs-per-argument","title":"Multiple Inputs Per Argument","text":"
As in the f_qs_relevance example, a selector for a single argument may point to more than one aspect of a record/app. These are specified using the slice or lists in key/index poisitions. In that case, the feedback function is evaluated multiple times, its outputs collected, and finally aggregated into a main feedback result.
The collection of values for each argument of feedback implementation is collected and every combination of argument-to-value mapping is evaluated with a feedback definition. This may produce a large number of evaluations if more than one argument names multiple values. In the dashboard, all individual invocations of a feedback implementation are shown alongside the final aggregate result.
"},{"location":"trulens_eval/feedback_function_guide/#apprecord-organization-what-can-be-selected","title":"App/Record Organization (What can be selected)","text":"
The top level JSON attributes are defined by the class structures.
For a Record:
class Record(SerialModel):\n record_id: RecordID\n app_id: AppID\n\n cost: Optional[Cost] = None\n perf: Optional[Perf] = None\n\n ts: datetime = pydantic.Field(default_factory=lambda: datetime.now())\n\n tags: str = \"\"\n\n main_input: Optional[JSON] = None\n main_output: Optional[JSON] = None # if no error\n main_error: Optional[JSON] = None # if error\n\n # The collection of calls recorded. Note that these can be converted into a\n # json structure with the same paths as the app that generated this record\n # via `layout_calls_as_app`.\n calls: Sequence[RecordAppCall] = []\n
For an App:
class AppDefinition(SerialModel, WithClassInfo, ABC):\n ...\n\n app_id: AppID\n\n feedback_definitions: Sequence[FeedbackDefinition] = []\n\n feedback_mode: FeedbackMode = FeedbackMode.WITH_APP_THREAD\n\n root_class: Class\n\n root_callable: ClassVar[FunctionOrMethod]\n\n app: JSON\n
For your app, you can inspect the JSON-like structure by using the dict method:
tru = ... # your app, extending App\nprint(tru.dict())\n
"},{"location":"trulens_eval/feedback_function_guide/#calls-made-by-app-components","title":"Calls made by App Components","text":"
When evaluating a feedback function, Records are augmented with app/component calls. For example, if the instrumented app contains a component combine_docs_chain then app.combine_docs_chain will contain calls to methods of this component. app.combine_docs_chain._call will contain a RecordAppCall (see schema.py) with information about the inputs/outputs/metadata regarding the _call call to that component. Selecting this information is the reason behind the Select.RecordCalls alias.
You can inspect the components making up your app via the App method print_instrumented.
"},{"location":"trulens_eval/function_definitions/","title":"Function Definitions","text":"
A feedback function scores the output of an LLM application by analyzing generated text as part of an LLM application (or a downstream model or application built on it). This guide provides details about the feedback functions that are implemented out of the box by TruLens. At the end of the guide, you can find additional information about how to create custom feedback functions.
See also: https://www.trulens.org/trulens_eval/api/feedback/
"},{"location":"trulens_eval/function_definitions/#relevance","title":"Relevance","text":"
This evaluates the relevance of the LLM response to the given text by LLM prompting.
Relevance is currently only available with OpenAI ChatCompletion API.
TruLens offers two particular flavors of relevance:
-
Prompt response relevance is best for measuring the relationship of the final answer to the user inputed question. This flavor of relevance is particularly optimized for the following features:
- Relevance requires adherence to the entire prompt.
- Responses that don't provide a definitive answer can still be relevant
- Admitting lack of knowledge and refusals are still relevant.
- Feedback mechanism should differentiate between seeming and actual relevance.
- Relevant but inconclusive statements should get increasingly high scores as they are more helpful for answering the query.
You can read more information about the performance of prompt response relevance by viewing its smoke test results.
-
Question statement relevance, sometimes known as context relevance, is best for measuring the relationship of a provided context to the user inputed question. This flavor of relevance is optimized for a slightly different set of features:
- Relevance requires adherence to the entire query.
- Long context with small relevant chunks are relevant.
- Context that provides no answer can still be relevant.
- Feedback mechanism should differentiate between seeming and actual relevance.
- Relevant but inconclusive statements should get increasingly high scores as they are more helpful for answering the query.
You can read more information about the performance of question statement relevance by viewing its smoke test results.
"},{"location":"trulens_eval/function_definitions/#groundedness","title":"Groundedness","text":"
Groundedness uses OpenAI LLMs or Huggingface NLI to attempt to check if an answer is grounded in its supplied contexts on a scale from 1 to 10. The information overlap or entailment between source and response is then measured, choosing the highest score between sources and then averaged and scaled from 0 to 1.
You can read about the performance of groundedness evaluations by viewing its smoke test results.
"},{"location":"trulens_eval/function_definitions/#sentiment","title":"Sentiment","text":"
This evaluates the positive sentiment of either the prompt or response.
Sentiment is currently available to use with OpenAI, HuggingFace or Cohere as the model provider.
- The OpenAI sentiment feedback function prompts a Chat Completion model to rate the sentiment from 1 to 10, and then scales the response down to 0-1.
- The HuggingFace sentiment feedback function returns a raw score from 0 to 1.
- The Cohere sentiment feedback function uses the classification endpoint and a small set of examples stored in
feedback_prompts.py to return either a 0 or a 1.
"},{"location":"trulens_eval/function_definitions/#model-agreement","title":"Model Agreement","text":"
Model agreement uses OpenAI to attempt an honest answer at your prompt with system prompts for correctness, and then evaluates the agreement of your LLM response to this model on a scale from 1 to 10. The agreement with each honest bot is then averaged and scaled from 0 to 1.
"},{"location":"trulens_eval/function_definitions/#language-match","title":"Language Match","text":"
This evaluates if the language of the prompt and response match.
Language match is currently only available to use with HuggingFace as the model provider. This feedback function returns a score in the range from 0 to 1, where 1 indicates match and 0 indicates mismatch.
"},{"location":"trulens_eval/function_definitions/#toxicity","title":"Toxicity","text":"
This evaluates the toxicity of the prompt or response.
Toxicity is currently only available to be used with HuggingFace, and uses a classification endpoint to return a score from 0 to 1. The feedback function is negated as not_toxicity, and returns a 1 if not toxic and a 0 if toxic.
"},{"location":"trulens_eval/function_definitions/#moderation","title":"Moderation","text":"
The OpenAI Moderation API is made available for use as feedback functions. This includes hate, hate/threatening, self-harm, sexual, sexual/minors, violence, and violence/graphic. Each is negated (ex: not_hate) so that a 0 would indicate that the moderation rule is violated. These feedback functions return a score in the range 0 to 1.
"},{"location":"trulens_eval/function_definitions/#stereotypes","title":"Stereotypes","text":"
This evaluates stereotypes using OpenAI LLMs to check if gender or race were assumed with no prior indication. This is rated on a scale from 1 to 10 where 10 being no new gender or race assumptions. A two indicates gender or race assumption with no indication, and a one indicates gender or race changes with prior indication that is different.
"},{"location":"trulens_eval/function_definitions/#summarization","title":"Summarization","text":"
This evaluates summarization tasks using OpenAI LLMs to check how well a summarization hits upon main points. This is rated on a scale from 1 to 10 where 10 being all points are addressed.
"},{"location":"trulens_eval/function_definitions/#embeddings-distance","title":"Embeddings Distance","text":"
Given an embedder, as is typical in vector DBs, this evaluates the distance of the query and document embeddings. Currently supporting cosine distance, L1/Manhattan distance, and L2/Euclidean distance.
"},{"location":"trulens_eval/gh_top_intro/","title":"Gh top intro","text":""},{"location":"trulens_eval/gh_top_intro/#welcome-to-trulens","title":"\ud83e\udd91 Welcome to TruLens!","text":"
TruLens provides a set of tools for developing and monitoring neural nets, including large language models. This includes both tools for evaluation of LLMs and LLM-based applications with TruLens-Eval and deep learning explainability with TruLens-Explain. TruLens-Eval and TruLens-Explain are housed in separate packages and can be used independently.
The best way to support TruLens is to give us a \u2b50 and join our slack community!
"},{"location":"trulens_eval/gh_top_intro/#trulens-eval","title":"TruLens-Eval","text":"
TruLens-Eval contains instrumentation and evaluation tools for large language model (LLM) based applications. It supports the iterative development and monitoring of a wide range of LLM applications by wrapping your application to log key metadata across the entire chain (or off chain if your project does not use chains) on your local machine. Importantly, it also gives you the tools you need to evaluate the quality of your LLM-based applications.
TruLens-Eval has two key value propositions:
- Evaluation:
- TruLens supports the the evaluation of inputs, outputs and internals of your LLM application using any model (including LLMs).
- A number of feedback functions for evaluation are implemented out-of-the-box such as groundedness, relevance and toxicity. The framework is also easily extensible for custom evaluation requirements.
- Tracking:
- TruLens contains instrumentation for any LLM application including question answering, retrieval-augmented generation, agent-based applications and more. This instrumentation allows for the tracking of a wide variety of usage metrics and metadata. Read more in the instrumentation overview.
- TruLens' instrumentation can be applied to any LLM application without being tied down to a given framework. Additionally, deep integrations with LangChain and Llama-Index allow the capture of internal metadata and text.
- Anything that is tracked by the instrumentation can be evaluated!
The process for building your evaluated and tracked LLM application with TruLens is shown below \ud83d\udc47
"},{"location":"trulens_eval/gh_top_intro/#installation-and-setup","title":"Installation and setup","text":"
Install trulens-eval from PyPI.
pip install trulens-eval\n
"},{"location":"trulens_eval/gh_top_intro/#quick-usage","title":"Quick Usage","text":"
TruLens supports the evaluation of tracking for any LLM app framework. Choose a framework below to get started:
Langchain
langchain_quickstart.ipynb.
Llama-Index
llama_index_quickstart.ipynb.
Custom Text to Text Apps
text2text_quickstart.ipynb.
"},{"location":"trulens_eval/groundedness_smoke_tests/","title":"Groundedness","text":"In\u00a0[1]: Copied!
# Import groundedness feedback function\nfrom trulens_eval.feedback import GroundTruthAgreement, Groundedness\nfrom trulens_eval import TruBasicApp, Feedback, Tru, Select\nfrom test_cases import generate_summeval_groundedness_golden_set\n\nTru().reset_database()\n\n# generator for groundedness golden set\ntest_cases_gen = generate_summeval_groundedness_golden_set(\"./datasets/summeval_test_100.json\")\n\n# generate x number of test cases\ngroundedness_golden_set = []\nfor i in range(50):\n groundedness_golden_set.append(next(test_cases_gen))\n
# Import groundedness feedback function from trulens_eval.feedback import GroundTruthAgreement, Groundedness from trulens_eval import TruBasicApp, Feedback, Tru, Select from test_cases import generate_summeval_groundedness_golden_set Tru().reset_database() # generator for groundedness golden set test_cases_gen = generate_summeval_groundedness_golden_set(\"./datasets/summeval_test_100.json\") # generate x number of test cases groundedness_golden_set = [] for i in range(50): groundedness_golden_set.append(next(test_cases_gen))
\ud83e\udd91 Tru initialized with db url sqlite:///default.sqlite .\n\ud83d\uded1 Secret keys may be written to the database. See the `database_redact_keys` option of `Tru` to prevent this.\nDeleted 0 rows.\n
In\u00a0[2]: Copied!
groundedness_golden_set[:3]\n
groundedness_golden_set[:3] Out[2]:
[{'query': '(CNN)Donald Sterling\\'s racist remarks cost him an NBA team last year. But now it\\'s his former female companion who has lost big. A Los Angeles judge has ordered V. Stiviano to pay back more than $2.6 million in gifts after Sterling\\'s wife sued her. In the lawsuit, Rochelle \"Shelly\" Sterling accused Stiviano of targeting extremely wealthy older men. She claimed Donald Sterling used the couple\\'s money to buy Stiviano a Ferrari, two Bentleys and a Range Rover, and that he helped her get a $1.8 million duplex. Who is V. Stiviano? Stiviano countered that there was nothing wrong with Donald Sterling giving her gifts and that she never took advantage of the former Los Angeles Clippers owner, who made much of his fortune in real estate. Shelly Sterling was thrilled with the court decision Tuesday, her lawyer told CNN affiliate KABC. \"This is a victory for the Sterling family in recovering the $2,630,000 that Donald lavished on a conniving mistress,\" attorney Pierce O\\'Donnell said in a statement. \"It also sets a precedent that the injured spouse can recover damages from the recipient of these ill-begotten gifts.\" Stiviano\\'s gifts from Donald Sterling didn\\'t just include uber-expensive items like luxury cars. According to the Los Angeles Times, the list also includes a $391 Easter bunny costume, a $299 two-speed blender and a $12 lace thong. Donald Sterling\\'s downfall came after an audio recording surfaced of the octogenarian arguing with Stiviano. In the tape, Sterling chastises Stiviano for posting pictures on social media of her posing with African-Americans, including basketball legend Magic Johnson. \"In your lousy f**ing Instagrams, you don\\'t have to have yourself with -- walking with black people,\" Sterling said in the audio first posted by TMZ. He also tells Stiviano not to bring Johnson to Clippers games and not to post photos with the Hall of Famer so Sterling\\'s friends can see. \"Admire him, bring him here, feed him, f**k him, but don\\'t put (Magic) on an Instagram for the world to have to see so they have to call me,\" Sterling said. NBA Commissioner Adam Silver banned Sterling from the league, fined him $2.5 million and pushed through a charge to terminate all of his ownership rights in the franchise. Fact check: Donald Sterling\\'s claims vs. reality CNN\\'s Dottie Evans contributed to this report.',\n 'response': \"donald sterling , nba team last year . sterling 's wife sued for $ 2.6 million in gifts . sterling says he is the former female companion who has lost the . sterling has ordered v. stiviano to pay back $ 2.6 m in gifts after his wife sued . sterling also includes a $ 391 easter bunny costume , $ 299 and a $ 299 .\",\n 'expected_score': 0.27},\n {'query': '(CNN)Donald Sterling\\'s racist remarks cost him an NBA team last year. But now it\\'s his former female companion who has lost big. A Los Angeles judge has ordered V. Stiviano to pay back more than $2.6 million in gifts after Sterling\\'s wife sued her. In the lawsuit, Rochelle \"Shelly\" Sterling accused Stiviano of targeting extremely wealthy older men. She claimed Donald Sterling used the couple\\'s money to buy Stiviano a Ferrari, two Bentleys and a Range Rover, and that he helped her get a $1.8 million duplex. Who is V. Stiviano? Stiviano countered that there was nothing wrong with Donald Sterling giving her gifts and that she never took advantage of the former Los Angeles Clippers owner, who made much of his fortune in real estate. Shelly Sterling was thrilled with the court decision Tuesday, her lawyer told CNN affiliate KABC. \"This is a victory for the Sterling family in recovering the $2,630,000 that Donald lavished on a conniving mistress,\" attorney Pierce O\\'Donnell said in a statement. \"It also sets a precedent that the injured spouse can recover damages from the recipient of these ill-begotten gifts.\" Stiviano\\'s gifts from Donald Sterling didn\\'t just include uber-expensive items like luxury cars. According to the Los Angeles Times, the list also includes a $391 Easter bunny costume, a $299 two-speed blender and a $12 lace thong. Donald Sterling\\'s downfall came after an audio recording surfaced of the octogenarian arguing with Stiviano. In the tape, Sterling chastises Stiviano for posting pictures on social media of her posing with African-Americans, including basketball legend Magic Johnson. \"In your lousy f**ing Instagrams, you don\\'t have to have yourself with -- walking with black people,\" Sterling said in the audio first posted by TMZ. He also tells Stiviano not to bring Johnson to Clippers games and not to post photos with the Hall of Famer so Sterling\\'s friends can see. \"Admire him, bring him here, feed him, f**k him, but don\\'t put (Magic) on an Instagram for the world to have to see so they have to call me,\" Sterling said. NBA Commissioner Adam Silver banned Sterling from the league, fined him $2.5 million and pushed through a charge to terminate all of his ownership rights in the franchise. Fact check: Donald Sterling\\'s claims vs. reality CNN\\'s Dottie Evans contributed to this report.',\n 'response': \"donald sterling accused stiviano of targeting extremely wealthy older men . she claimed donald sterling used the couple 's money to buy stiviano a ferrari , two bentleys and a range rover . stiviano countered that there was nothing wrong with donald sterling giving her gifts .\",\n 'expected_score': 0.4},\n {'query': '(CNN)Donald Sterling\\'s racist remarks cost him an NBA team last year. But now it\\'s his former female companion who has lost big. A Los Angeles judge has ordered V. Stiviano to pay back more than $2.6 million in gifts after Sterling\\'s wife sued her. In the lawsuit, Rochelle \"Shelly\" Sterling accused Stiviano of targeting extremely wealthy older men. She claimed Donald Sterling used the couple\\'s money to buy Stiviano a Ferrari, two Bentleys and a Range Rover, and that he helped her get a $1.8 million duplex. Who is V. Stiviano? Stiviano countered that there was nothing wrong with Donald Sterling giving her gifts and that she never took advantage of the former Los Angeles Clippers owner, who made much of his fortune in real estate. Shelly Sterling was thrilled with the court decision Tuesday, her lawyer told CNN affiliate KABC. \"This is a victory for the Sterling family in recovering the $2,630,000 that Donald lavished on a conniving mistress,\" attorney Pierce O\\'Donnell said in a statement. \"It also sets a precedent that the injured spouse can recover damages from the recipient of these ill-begotten gifts.\" Stiviano\\'s gifts from Donald Sterling didn\\'t just include uber-expensive items like luxury cars. According to the Los Angeles Times, the list also includes a $391 Easter bunny costume, a $299 two-speed blender and a $12 lace thong. Donald Sterling\\'s downfall came after an audio recording surfaced of the octogenarian arguing with Stiviano. In the tape, Sterling chastises Stiviano for posting pictures on social media of her posing with African-Americans, including basketball legend Magic Johnson. \"In your lousy f**ing Instagrams, you don\\'t have to have yourself with -- walking with black people,\" Sterling said in the audio first posted by TMZ. He also tells Stiviano not to bring Johnson to Clippers games and not to post photos with the Hall of Famer so Sterling\\'s friends can see. \"Admire him, bring him here, feed him, f**k him, but don\\'t put (Magic) on an Instagram for the world to have to see so they have to call me,\" Sterling said. NBA Commissioner Adam Silver banned Sterling from the league, fined him $2.5 million and pushed through a charge to terminate all of his ownership rights in the franchise. Fact check: Donald Sterling\\'s claims vs. reality CNN\\'s Dottie Evans contributed to this report.',\n 'response': \"a los angeles judge has ordered v. stiviano to pay back more than $ 2.6 million in gifts after sterling 's wife sued her . -lrb- cnn -rrb- donald sterling 's racist remarks cost him an nba team last year . but now it 's his former female companion who has lost big . who is v. stiviano ? .\",\n 'expected_score': 0.7}] In\u00a0[3]: Copied!
import os\nos.environ[\"OPENAI_API_KEY\"] = \"...\"\nos.environ[\"HUGGINGFACE_API_KEY\"] = \"...\"\n
import os os.environ[\"OPENAI_API_KEY\"] = \"...\" os.environ[\"HUGGINGFACE_API_KEY\"] = \"...\" In\u00a0[4]: Copied!
from trulens_eval.feedback.provider.hugs import Huggingface\nfrom trulens_eval.feedback.provider import OpenAI\nimport numpy as np\n\nhuggingface_provider = Huggingface()\ngroundedness_hug = Groundedness(groundedness_provider=huggingface_provider)\nf_groundedness_hug = Feedback(groundedness_hug.groundedness_measure, name = \"Groundedness Huggingface\").on_input().on_output().aggregate(groundedness_hug.grounded_statements_aggregator)\ndef wrapped_groundedness_hug(input, output):\n return np.mean(list(f_groundedness_hug(input, output)[0].values()))\n \n \n \ngroundedness_openai = Groundedness(groundedness_provider=OpenAI(model_engine=\"gpt-3.5-turbo\")) # GPT-3.5-turbot being the default model if not specified\nf_groundedness_openai = Feedback(groundedness_openai.groundedness_measure, name = \"Groundedness OpenAI GPT-3.5\").on_input().on_output().aggregate(groundedness_openai.grounded_statements_aggregator)\ndef wrapped_groundedness_openai(input, output):\n return f_groundedness_openai(input, output)[0]['full_doc_score']\n\ngroundedness_openai_gpt4 = Groundedness(groundedness_provider=OpenAI(model_engine=\"gpt-4\"))\nf_groundedness_openai_gpt4 = Feedback(groundedness_openai_gpt4.groundedness_measure, name = \"Groundedness OpenAI GPT-4\").on_input().on_output().aggregate(groundedness_openai_gpt4.grounded_statements_aggregator)\ndef wrapped_groundedness_openai_gpt4(input, output):\n return f_groundedness_openai_gpt4(input, output)[0]['full_doc_score']\n
from trulens_eval.feedback.provider.hugs import Huggingface from trulens_eval.feedback.provider import OpenAI import numpy as np huggingface_provider = Huggingface() groundedness_hug = Groundedness(groundedness_provider=huggingface_provider) f_groundedness_hug = Feedback(groundedness_hug.groundedness_measure, name = \"Groundedness Huggingface\").on_input().on_output().aggregate(groundedness_hug.grounded_statements_aggregator) def wrapped_groundedness_hug(input, output): return np.mean(list(f_groundedness_hug(input, output)[0].values())) groundedness_openai = Groundedness(groundedness_provider=OpenAI(model_engine=\"gpt-3.5-turbo\")) # GPT-3.5-turbot being the default model if not specified f_groundedness_openai = Feedback(groundedness_openai.groundedness_measure, name = \"Groundedness OpenAI GPT-3.5\").on_input().on_output().aggregate(groundedness_openai.grounded_statements_aggregator) def wrapped_groundedness_openai(input, output): return f_groundedness_openai(input, output)[0]['full_doc_score'] groundedness_openai_gpt4 = Groundedness(groundedness_provider=OpenAI(model_engine=\"gpt-4\")) f_groundedness_openai_gpt4 = Feedback(groundedness_openai_gpt4.groundedness_measure, name = \"Groundedness OpenAI GPT-4\").on_input().on_output().aggregate(groundedness_openai_gpt4.grounded_statements_aggregator) def wrapped_groundedness_openai_gpt4(input, output): return f_groundedness_openai_gpt4(input, output)[0]['full_doc_score']
\u2705 In Groundedness Huggingface, input source will be set to __record__.main_input or `Select.RecordInput` .\n\u2705 In Groundedness Huggingface, input statement will be set to __record__.main_output or `Select.RecordOutput` .\n\u2705 In Groundedness OpenAI GPT-3.5, input source will be set to __record__.main_input or `Select.RecordInput` .\n\u2705 In Groundedness OpenAI GPT-3.5, input statement will be set to __record__.main_output or `Select.RecordOutput` .\n\u2705 In Groundedness OpenAI GPT-4, input source will be set to __record__.main_input or `Select.RecordInput` .\n\u2705 In Groundedness OpenAI GPT-4, input statement will be set to __record__.main_output or `Select.RecordOutput` .\n
In\u00a0[5]: Copied!
# Create a Feedback object using the numeric_difference method of the ground_truth object\nground_truth = GroundTruthAgreement(groundedness_golden_set)\n# Call the numeric_difference method with app and record and aggregate to get the mean absolute error\nf_mae = Feedback(ground_truth.mae, name = \"Mean Absolute Error\").on(Select.Record.calls[0].args.args[0]).on(Select.Record.calls[0].args.args[1]).on_output()\n
# Create a Feedback object using the numeric_difference method of the ground_truth object ground_truth = GroundTruthAgreement(groundedness_golden_set) # Call the numeric_difference method with app and record and aggregate to get the mean absolute error f_mae = Feedback(ground_truth.mae, name = \"Mean Absolute Error\").on(Select.Record.calls[0].args.args[0]).on(Select.Record.calls[0].args.args[1]).on_output()
\u2705 In Mean Absolute Error, input prompt will be set to __record__.calls[0].args.args[0] .\n\u2705 In Mean Absolute Error, input response will be set to __record__.calls[0].args.args[1] .\n\u2705 In Mean Absolute Error, input score will be set to __record__.main_output or `Select.RecordOutput` .\n
In\u00a0[6]: Copied!
tru_wrapped_groundedness_hug = TruBasicApp(wrapped_groundedness_hug, app_id = \"groundedness huggingface\", feedbacks=[f_mae])\ntru_wrapped_groundedness_openai = TruBasicApp(wrapped_groundedness_openai, app_id = \"groundedness openai gpt-3.5\", feedbacks=[f_mae])\ntru_wrapped_groundedness_openai_gpt4 = TruBasicApp(wrapped_groundedness_openai_gpt4, app_id = \"groundedness openai gpt-4\", feedbacks=[f_mae])\n
tru_wrapped_groundedness_hug = TruBasicApp(wrapped_groundedness_hug, app_id = \"groundedness huggingface\", feedbacks=[f_mae]) tru_wrapped_groundedness_openai = TruBasicApp(wrapped_groundedness_openai, app_id = \"groundedness openai gpt-3.5\", feedbacks=[f_mae]) tru_wrapped_groundedness_openai_gpt4 = TruBasicApp(wrapped_groundedness_openai_gpt4, app_id = \"groundedness openai gpt-4\", feedbacks=[f_mae])
\u2705 added app groundedness huggingface\n\u2705 added feedback definition feedback_definition_hash_ca9bbb2338965a9d34e17ae53f641d9c\n\u2705 added app groundedness openai\n\u2705 added feedback definition feedback_definition_hash_ca9bbb2338965a9d34e17ae53f641d9c\n\u2705 added app groundedness openai gpt4\n\u2705 added feedback definition feedback_definition_hash_ca9bbb2338965a9d34e17ae53f641d9c\n
In\u00a0[\u00a0]: Copied!
for i in range(len(groundedness_golden_set)):\n source = groundedness_golden_set[i][\"query\"]\n response = groundedness_golden_set[i][\"response\"]\n with tru_wrapped_groundedness_hug as recording:\n tru_wrapped_groundedness_hug.app(source, response)\n with tru_wrapped_groundedness_openai as recording:\n tru_wrapped_groundedness_openai.app(source, response)\n with tru_wrapped_groundedness_openai_gpt4 as recording:\n tru_wrapped_groundedness_openai_gpt4.app(source, response)\n
for i in range(len(groundedness_golden_set)): source = groundedness_golden_set[i][\"query\"] response = groundedness_golden_set[i][\"response\"] with tru_wrapped_groundedness_hug as recording: tru_wrapped_groundedness_hug.app(source, response) with tru_wrapped_groundedness_openai as recording: tru_wrapped_groundedness_openai.app(source, response) with tru_wrapped_groundedness_openai_gpt4 as recording: tru_wrapped_groundedness_openai_gpt4.app(source, response) In\u00a0[9]: Copied!
Tru().get_leaderboard(app_ids=[]).sort_values(by=\"Mean Absolute Error\")\n
Tru().get_leaderboard(app_ids=[]).sort_values(by=\"Mean Absolute Error\") Out[9]: Mean Absolute Error latency total_cost app_id groundedness huggingface 0.251471 2.4 0.000000 groundedness openai 2.371200 2.4 0.001344 groundedness openai gpt4 2.371200 2.4 0.001464"},{"location":"trulens_eval/groundedness_smoke_tests/#groundedness-evaluations","title":"Groundedness Evaluations\u00b6","text":"
In many ways, feedbacks can be thought of as LLM apps themselves. Given text, they return some result. Thinking in this way, we can use TruLens to evaluate and track our feedback quality. We can even do this for different models (e.g. gpt-3.5 and gpt-4) or prompting schemes (such as chain-of-thought reasoning).
This notebook follows an evaluation of a set of test cases generated from human annotated datasets. In particular, we generate test cases from SummEval.
SummEval is one of the datasets dedicated to automated evaluations on summarization tasks, which are closely related to the groundedness evaluation in RAG with the retrieved context (i.e. the source) and response (i.e. the summary). It contains human annotation of numerical score (1 to 5) comprised of scoring from 3 human expert annotators and 5 croweded-sourced annotators. There are 16 models being used for generation in total for 100 paragraphs in the test set, so there are a total of 16,000 machine-generated summaries. Each paragraph also has several human-written summaries for comparative analysis.
For evaluating groundedness feedback functions, we calculate the annotated \"relevance\" and \"consistency (aka factuality)\" scores with equal weights and normalized to 0 to 1 score to match the output of feedback functions.
"},{"location":"trulens_eval/groundedness_smoke_tests/#benchmarking-various-groundedness-feedback-function-providers-openai-gpt-35-turbo-vs-gpt-4-vs-huggingface","title":"Benchmarking various Groundedness feedback function providers (OpenAI GPT-3.5-turbo vs GPT-4 vs Huggingface)\u00b6","text":""},{"location":"trulens_eval/install/","title":"\ud83d\ude80 Installation","text":""},{"location":"trulens_eval/install/#getting-access-to-trulens","title":"Getting access to TruLens","text":"
These installation instructions assume that you have conda installed and added to your path.
-
Create a virtual environment (or modify an existing one).
conda create -n \"<my_name>\" python=3 # Skip if using existing environment.\nconda activate <my_name>\n
-
[Pip installation] Install the trulens-eval pip package from PyPI.
pip install trulens-eval\n
-
[Local installation] If you would like to develop or modify TruLens, you can download the source code by cloning the TruLens repo.
git clone https://github.com/truera/trulens.git\n
-
[Local installation] Install the TruLens repo.
cd trulens/trulens_eval\npip install -e .\n
"},{"location":"trulens_eval/intro/","title":"Welcome to TruLens-Eval!","text":"
Evaluate and track your LLM experiments with TruLens. As you work on your models and prompts TruLens-Eval supports the iterative development and of a wide range of LLM applications by wrapping your application to log key metadata across the entire chain (or off chain if your project does not use chains) on your local machine.
Using feedback functions, you can objectively evaluate the quality of the responses provided by an LLM to your requests. This is completed with minimal latency, as this is achieved in a sequential call for your application, and evaluations are logged to your local machine. Finally, we provide an easy to use Streamlit dashboard run locally on your machine for you to better understand your LLM\u2019s performance.
"},{"location":"trulens_eval/intro/#value-propositions","title":"Value Propositions","text":"
TruLens-Eval has two key value propositions:
- Evaluation:
- TruLens supports the the evaluation of inputs, outputs and internals of your LLM application using any model (including LLMs).
- A number of feedback functions for evaluation are implemented out-of-the-box such as groundedness, relevance and toxicity. The framework is also easily extensible for custom evaluation requirements.
- Tracking:
- TruLens contains instrumentation for any LLM application including question answering, retrieval-augmented generation, agent-based applications and more. This instrumentation allows for the tracking of a wide variety of usage metrics and metadata. Read more in the instrumentation overview.
- TruLens' instrumentation can be applied to any LLM application without being tied down to a given framework. Additionally, deep integrations with LangChain and Llama-Index allow the capture of internal metadata and text.
- Anything that is tracked by the instrumentation can be evaluated!
The process for building your evaluated and tracked LLM application with TruLens is below \ud83d\udc47
"},{"location":"trulens_eval/intro/#installation-and-setup","title":"Installation and Setup","text":"
Install the trulens-eval pip package from PyPI.
pip install trulens-eval\n
"},{"location":"trulens_eval/intro/#setting-keys","title":"Setting Keys","text":"
In any of the quickstarts, you will need OpenAI and Huggingface keys. You can add keys by setting the environmental variables:
import os\nos.environ[\"OPENAI_API_KEY\"] = \"...\"\nos.environ[\"HUGGINGFACE_API_KEY\"] = \"...\"\n
"},{"location":"trulens_eval/intro/#quick-usage","title":"Quick Usage","text":"
TruLens supports the evaluation of tracking for any LLM app framework. Choose a framework below to get started:
Langchain
langchain_quickstart.ipynb.
Llama-Index
llama_index_quickstart.ipynb.
Custom Text to Text Apps
text2text_quickstart.ipynb.
"},{"location":"trulens_eval/intro/#contributing","title":"\ud83d\udca1 Contributing","text":"
Interested in contributing? See our contribution guide for more details.
"},{"location":"trulens_eval/langchain_instrumentation/","title":"LangChain Integration","text":"In\u00a0[\u00a0]: Copied!
# required imports\nfrom langchain.chains import LLMChain\nfrom langchain.llms import OpenAI\nfrom langchain.prompts.chat import HumanMessagePromptTemplate, ChatPromptTemplate, PromptTemplate\nfrom trulens_eval import TruChain\n\n# typical langchain setup\nfull_prompt = HumanMessagePromptTemplate(\n prompt=PromptTemplate(\n template=\n \"Provide a helpful response with relevant background information for the following: {prompt}\",\n input_variables=[\"prompt\"],\n )\n)\nchat_prompt_template = ChatPromptTemplate.from_messages([full_prompt])\n\nllm = OpenAI(temperature=0.9, max_tokens=128)\nchain = LLMChain(llm=llm, prompt=chat_prompt_template, verbose=True)\n # required imports from langchain.chains import LLMChain from langchain.llms import OpenAI from langchain.prompts.chat import HumanMessagePromptTemplate, ChatPromptTemplate, PromptTemplate from trulens_eval import TruChain # typical langchain setup full_prompt = HumanMessagePromptTemplate( prompt=PromptTemplate( template= \"Provide a helpful response with relevant background information for the following: {prompt}\", input_variables=[\"prompt\"], ) ) chat_prompt_template = ChatPromptTemplate.from_messages([full_prompt]) llm = OpenAI(temperature=0.9, max_tokens=128) chain = LLMChain(llm=llm, prompt=chat_prompt_template, verbose=True)
To instrument an LLM chain, all that's required is to wrap it using TruChain.
In\u00a0[\u00a0]: Copied!
# instrument with TruChain\ntru_recorder = TruChain(chain)\n
# instrument with TruChain tru_recorder = TruChain(chain)
You can find the full quickstart available here: LangChain Quickstart
In\u00a0[\u00a0]: Copied!
from langchain import LLMChain\nfrom langchain import PromptTemplate\nfrom langchain.callbacks import AsyncIteratorCallbackHandler\nfrom langchain.chains import LLMChain\nfrom langchain.chat_models.openai import ChatOpenAI\n\nfrom trulens_eval import TruChain\n\n# Set up an async callback.\ncallback = AsyncIteratorCallbackHandler()\n\n# Setup a simple question/answer chain with streaming ChatOpenAI.\nprompt = PromptTemplate.from_template(\"Honestly answer this question: {question}.\")\nllm = ChatOpenAI(\n temperature=0.0,\n streaming=True, # important\n callbacks=[callback] # callback can be here or below in acall_with_record\n)\nasync_chain = LLMChain(llm=llm, prompt=prompt)\n from langchain import LLMChain from langchain import PromptTemplate from langchain.callbacks import AsyncIteratorCallbackHandler from langchain.chains import LLMChain from langchain.chat_models.openai import ChatOpenAI from trulens_eval import TruChain # Set up an async callback. callback = AsyncIteratorCallbackHandler() # Setup a simple question/answer chain with streaming ChatOpenAI. prompt = PromptTemplate.from_template(\"Honestly answer this question: {question}.\") llm = ChatOpenAI( temperature=0.0, streaming=True, # important callbacks=[callback] # callback can be here or below in acall_with_record ) async_chain = LLMChain(llm=llm, prompt=prompt)
Once you have created the async LLM chain you can instrument it just as before.
In\u00a0[\u00a0]: Copied!
async_tc_recorder = TruChain(async_chain)\n\nwith async_tc_recorder as recording:\n await async_chain.acall(inputs=dict(question=\"What is 1+2? Explain your answer.\"))\n
async_tc_recorder = TruChain(async_chain) with async_tc_recorder as recording: await async_chain.acall(inputs=dict(question=\"What is 1+2? Explain your answer.\"))
For more usage examples, check out the LangChain examples directory.
"},{"location":"trulens_eval/langchain_instrumentation/#langchain-integration","title":"LangChain Integration\u00b6","text":"
TruLens provides TruChain, a deep integration with LangChain to allow you to inspect and evaluate the internals of your application built using LangChain.
TruChain captures all of the metrics and metadata listed in the instrumentation overview. In addition, TruChain instruments the following LangChain classes:
"},{"location":"trulens_eval/langchain_instrumentation/#instrumented-classes","title":"Instrumented Classes\u00b6","text":"
- langchain.chains.base.Chain
- langchain.vectorstores.base.BaseRetriever
- langchain.schema.BaseRetriever
- langchain.llms.base.BaseLLM
- langchain.prompts.base.BasePromptTemplate
- langchain.schema.BaseMemory
- langchain.schema.BaseChatMessageHistory
"},{"location":"trulens_eval/langchain_instrumentation/#example-usage","title":"Example Usage\u00b6","text":"
Below is a quick example of usage. First, we'll create a standard LLMChain.
"},{"location":"trulens_eval/langchain_instrumentation/#async-support","title":"Async Support\u00b6","text":"
TruChain also provides async support for Langchain through the acall method. This allows you to track and evaluate async and streaming LangChain applications.
As an example, below is an LLM chain set up with an async callback.
"},{"location":"trulens_eval/langchain_quickstart/","title":"Langchain Quickstart","text":"In\u00a0[\u00a0]: Copied!
# ! pip install trulens_eval==0.17.0 langchain>=0.0.263\n
# ! pip install trulens_eval==0.17.0 langchain>=0.0.263 In\u00a0[\u00a0]: Copied!
import os\nos.environ[\"OPENAI_API_KEY\"] = \"...\"\nos.environ[\"HUGGINGFACE_API_KEY\"] = \"...\"\n
import os os.environ[\"OPENAI_API_KEY\"] = \"...\" os.environ[\"HUGGINGFACE_API_KEY\"] = \"...\" In\u00a0[\u00a0]: Copied!
from IPython.display import JSON\n\n# Imports main tools:\nfrom trulens_eval import TruChain, Feedback, Huggingface, Tru\nfrom trulens_eval.schema import FeedbackResult\ntru = Tru()\n\n# Imports from langchain to build app. You may need to install langchain first\n# with the following:\n# ! pip install langchain>=0.0.170\nfrom langchain.chains import LLMChain\nfrom langchain.llms import OpenAI\nfrom langchain.prompts.chat import ChatPromptTemplate, PromptTemplate\nfrom langchain.prompts.chat import HumanMessagePromptTemplate\n
from IPython.display import JSON # Imports main tools: from trulens_eval import TruChain, Feedback, Huggingface, Tru from trulens_eval.schema import FeedbackResult tru = Tru() # Imports from langchain to build app. You may need to install langchain first # with the following: # ! pip install langchain>=0.0.170 from langchain.chains import LLMChain from langchain.llms import OpenAI from langchain.prompts.chat import ChatPromptTemplate, PromptTemplate from langchain.prompts.chat import HumanMessagePromptTemplate In\u00a0[\u00a0]: Copied!
full_prompt = HumanMessagePromptTemplate(\n prompt=PromptTemplate(\n template=\n \"Provide a helpful response with relevant background information for the following: {prompt}\",\n input_variables=[\"prompt\"],\n )\n)\n\nchat_prompt_template = ChatPromptTemplate.from_messages([full_prompt])\n\nllm = OpenAI(temperature=0.9, max_tokens=128)\n\nchain = LLMChain(llm=llm, prompt=chat_prompt_template, verbose=True)\n full_prompt = HumanMessagePromptTemplate( prompt=PromptTemplate( template= \"Provide a helpful response with relevant background information for the following: {prompt}\", input_variables=[\"prompt\"], ) ) chat_prompt_template = ChatPromptTemplate.from_messages([full_prompt]) llm = OpenAI(temperature=0.9, max_tokens=128) chain = LLMChain(llm=llm, prompt=chat_prompt_template, verbose=True) In\u00a0[\u00a0]: Copied!
prompt_input = '\u00bfque hora es?'\n
prompt_input = '\u00bfque hora es?' In\u00a0[\u00a0]: Copied!
llm_response = chain(prompt_input)\n\ndisplay(llm_response)\n
llm_response = chain(prompt_input) display(llm_response) In\u00a0[\u00a0]: Copied!
# Initialize Huggingface-based feedback function collection class:\nhugs = Huggingface()\n\n# Define a language match feedback function using HuggingFace.\nf_lang_match = Feedback(hugs.language_match).on_input_output()\n# By default this will check language match on the main app input and main app\n# output.\n
# Initialize Huggingface-based feedback function collection class: hugs = Huggingface() # Define a language match feedback function using HuggingFace. f_lang_match = Feedback(hugs.language_match).on_input_output() # By default this will check language match on the main app input and main app # output. In\u00a0[\u00a0]: Copied!
tru_recorder = TruChain(chain,\n app_id='Chain1_ChatApplication',\n feedbacks=[f_lang_match])\n
tru_recorder = TruChain(chain, app_id='Chain1_ChatApplication', feedbacks=[f_lang_match]) In\u00a0[\u00a0]: Copied!
with tru_recorder as recording:\n llm_response = chain(prompt_input)\n\ndisplay(llm_response)\n
with tru_recorder as recording: llm_response = chain(prompt_input) display(llm_response) In\u00a0[\u00a0]: Copied!
# The record of the ap invocation can be retrieved from the `recording`:\n\nrec = recording.get() # use .get if only one record\n# recs = recording.records # use .records if multiple\n\ndisplay(rec)\n
# The record of the ap invocation can be retrieved from the `recording`: rec = recording.get() # use .get if only one record # recs = recording.records # use .records if multiple display(rec) In\u00a0[\u00a0]: Copied!
# The results of the feedback functions can be rertireved from the record. These\n# are `Future` instances (see `concurrent.futures`). You can use `as_completed`\n# to wait until they have finished evaluating.\n\nfrom concurrent.futures import as_completed\n\nfor feedback_future in as_completed(rec.feedback_results):\n feedback, feedback_result = feedback_future.result()\n \n feedback: Feedback\n feedbac_result: FeedbackResult\n\n display(feedback.name, feedback_result.result)\n
# The results of the feedback functions can be rertireved from the record. These # are `Future` instances (see `concurrent.futures`). You can use `as_completed` # to wait until they have finished evaluating. from concurrent.futures import as_completed for feedback_future in as_completed(rec.feedback_results): feedback, feedback_result = feedback_future.result() feedback: Feedback feedbac_result: FeedbackResult display(feedback.name, feedback_result.result) In\u00a0[\u00a0]: Copied!
tru.run_dashboard() # open a local streamlit app to explore\n\n# tru.stop_dashboard() # stop if needed\n
tru.run_dashboard() # open a local streamlit app to explore # tru.stop_dashboard() # stop if needed
Alternatively, you can run trulens-eval from a command line in the same folder to start the dashboard.
Note: Feedback functions evaluated in the deferred manner can be seen in the \"Progress\" page of the TruLens dashboard.
In\u00a0[\u00a0]: Copied!
tru.get_records_and_feedback(app_ids=[])[0] # pass an empty list of app_ids to get all\n
tru.get_records_and_feedback(app_ids=[])[0] # pass an empty list of app_ids to get all"},{"location":"trulens_eval/langchain_quickstart/#langchain-quickstart","title":"Langchain Quickstart\u00b6","text":"
In this quickstart you will create a simple LLM Chain and learn how to log it and get feedback on an LLM response.
"},{"location":"trulens_eval/langchain_quickstart/#setup","title":"Setup\u00b6","text":""},{"location":"trulens_eval/langchain_quickstart/#add-api-keys","title":"Add API keys\u00b6","text":"
For this quickstart you will need Open AI and Huggingface keys
"},{"location":"trulens_eval/langchain_quickstart/#import-from-langchain-and-trulens","title":"Import from LangChain and TruLens\u00b6","text":""},{"location":"trulens_eval/langchain_quickstart/#create-simple-llm-application","title":"Create Simple LLM Application\u00b6","text":"
This example uses a LangChain framework and OpenAI LLM
"},{"location":"trulens_eval/langchain_quickstart/#send-your-first-request","title":"Send your first request\u00b6","text":""},{"location":"trulens_eval/langchain_quickstart/#initialize-feedback-functions","title":"Initialize Feedback Function(s)\u00b6","text":""},{"location":"trulens_eval/langchain_quickstart/#instrument-chain-for-logging-with-trulens","title":"Instrument chain for logging with TruLens\u00b6","text":""},{"location":"trulens_eval/langchain_quickstart/#retrieve-records-and-feedback","title":"Retrieve records and feedback\u00b6","text":""},{"location":"trulens_eval/langchain_quickstart/#explore-in-a-dashboard","title":"Explore in a Dashboard\u00b6","text":""},{"location":"trulens_eval/langchain_quickstart/#chain-leaderboard","title":"Chain Leaderboard\u00b6","text":"
Understand how your LLM application is performing at a glance. Once you've set up logging and evaluation in your application, you can view key performance statistics including cost and average feedback value across all of your LLM apps using the chain leaderboard. As you iterate new versions of your LLM application, you can compare their performance across all of the different quality metrics you've set up.
Note: Average feedback values are returned and displayed in a range from 0 (worst) to 1 (best).
To dive deeper on a particular chain, click \"Select Chain\".
"},{"location":"trulens_eval/langchain_quickstart/#understand-chain-performance-with-evaluations","title":"Understand chain performance with Evaluations\u00b6","text":"
To learn more about the performance of a particular chain or LLM model, we can select it to view its evaluations at the record level. LLM quality is assessed through the use of feedback functions. Feedback functions are extensible methods for determining the quality of LLM responses and can be applied to any downstream LLM task. Out of the box we provide a number of feedback functions for assessing model agreement, sentiment, relevance and more.
The evaluations tab provides record-level metadata and feedback on the quality of your LLM application.
"},{"location":"trulens_eval/langchain_quickstart/#deep-dive-into-full-chain-metadata","title":"Deep dive into full chain metadata\u00b6","text":"
Click on a record to dive deep into all of the details of your chain stack and underlying LLM, captured by tru_chain_recorder.
If you prefer the raw format, you can quickly get it using the \"Display full chain json\" or \"Display full record json\" buttons at the bottom of the page.
"},{"location":"trulens_eval/langchain_quickstart/#or-view-results-directly-in-your-notebook","title":"Or view results directly in your notebook\u00b6","text":""},{"location":"trulens_eval/llama_index_instrumentation/","title":"Llama-Index Integration","text":"In\u00a0[\u00a0]: Copied!
from llama_index import VectorStoreIndex, SimpleWebPageReader\nfrom trulens_eval import TruLlama\n\ndocuments = SimpleWebPageReader(html_to_text=True).load_data(\n [\"http://paulgraham.com/worked.html\"]\n)\nindex = VectorStoreIndex.from_documents(documents)\n\nquery_engine = index.as_query_engine()\n
from llama_index import VectorStoreIndex, SimpleWebPageReader from trulens_eval import TruLlama documents = SimpleWebPageReader(html_to_text=True).load_data( [\"http://paulgraham.com/worked.html\"] ) index = VectorStoreIndex.from_documents(documents) query_engine = index.as_query_engine()
To instrument an Llama-Index query engine, all that's required is to wrap it using TruLlama.
In\u00a0[\u00a0]: Copied!
tru_query_engine_recorder = TruLlama(query_engine)\n\nwith tru_query_engine_recorder as recording:\n llm_response = query_engine.query(\"What did the author do growing up?\")\n
tru_query_engine_recorder = TruLlama(query_engine) with tru_query_engine_recorder as recording: llm_response = query_engine.query(\"What did the author do growing up?\")
You can find the full quickstart available here: Llama-Index Quickstart
In\u00a0[\u00a0]: Copied!
# Imports main tools:\nfrom trulens_eval import TruLlama, Feedback, Tru, feedback, Select\ntru = Tru()\n\nfrom llama_index import VectorStoreIndex, SimpleWebPageReader\n\ndocuments = SimpleWebPageReader(html_to_text=True).load_data(\n [\"http://paulgraham.com/worked.html\"]\n)\nindex = VectorStoreIndex.from_documents(documents)\n\nchat_engine = index.as_chat_engine(streaming=True)\n
# Imports main tools: from trulens_eval import TruLlama, Feedback, Tru, feedback, Select tru = Tru() from llama_index import VectorStoreIndex, SimpleWebPageReader documents = SimpleWebPageReader(html_to_text=True).load_data( [\"http://paulgraham.com/worked.html\"] ) index = VectorStoreIndex.from_documents(documents) chat_engine = index.as_chat_engine(streaming=True)
To instrument an Llama-Index achat engine, all that's required is to wrap it using TruLlama - just like with the query engine.
In\u00a0[\u00a0]: Copied!
tru_chat_recorder = TruLlama(chat_engine)\n\nwith tru_chat_recorder as recording:\n llm_response_async = await chat_engine.aquery(\"What did the author do growing up?\")\n\nprint(llm_response_async)\n
tru_chat_recorder = TruLlama(chat_engine) with tru_chat_recorder as recording: llm_response_async = await chat_engine.aquery(\"What did the author do growing up?\") print(llm_response_async) In\u00a0[\u00a0]: Copied!
from llama_index import VectorStoreIndex, SimpleWebPageReader\nfrom trulens_eval import TruLlama\n\ndocuments = SimpleWebPageReader(html_to_text=True).load_data(\n [\"http://paulgraham.com/worked.html\"]\n)\nindex = VectorStoreIndex.from_documents(documents)\n\nquery_engine = index.as_query_engine(streaming=True)\n
from llama_index import VectorStoreIndex, SimpleWebPageReader from trulens_eval import TruLlama documents = SimpleWebPageReader(html_to_text=True).load_data( [\"http://paulgraham.com/worked.html\"] ) index = VectorStoreIndex.from_documents(documents) query_engine = index.as_query_engine(streaming=True)
Just like with other methods, just wrap your streaming query engine with TruLlama and operate like before.
You can also print the response tokens as they are generated using the response_gen attribute.
In\u00a0[\u00a0]: Copied!
tru_query_engine_recorder = TruLlama(query_engine)\n\nwith tru_query_engine_recorder as recording:\n response = query_engine.query(\"What did the author do growing up?\")\n\nfor c in response.response_gen:\n print(c)\n
tru_query_engine_recorder = TruLlama(query_engine) with tru_query_engine_recorder as recording: response = query_engine.query(\"What did the author do growing up?\") for c in response.response_gen: print(c)
For more usage examples, check out the Llama-Index examples directory.
"},{"location":"trulens_eval/llama_index_instrumentation/#llama-index-integration","title":"Llama-Index Integration\u00b6","text":"
TruLens provides TruLlama, a deep integration with Llama-Index to allow you to inspect and evaluate the internals of your application built using Llama-Index.
TruLlama captures all of the metrics and metadata listed in the instrumentation overview. In addition, TruLlama provides the select_source_nodes method to capture the source nodes of your query.
"},{"location":"trulens_eval/llama_index_instrumentation/#supported-methods","title":"Supported methods\u00b6","text":"
TruLlama supports both sync and async modes using the following Llama-Index query engine methods:
queryaquerychatachatstream_chatastream_chat
"},{"location":"trulens_eval/llama_index_instrumentation/#example-usage","title":"Example usage\u00b6","text":"
Below is a quick example of usage. First, we'll create a standard Llama-Index query engine from Paul Graham's Essay, What I Worked On
"},{"location":"trulens_eval/llama_index_instrumentation/#async-support","title":"Async Support\u00b6","text":"
TruLlama also provides async support for Llama-Index through the aquery, achat, and astream_chat methods. This allows you to track and evaluate async applciations.
As an example, below is an Llama-Index async chat engine (achat).
"},{"location":"trulens_eval/llama_index_instrumentation/#streaming-support","title":"Streaming Support\u00b6","text":"
TruLlama also provides streaming support for Llama-Index. This allows you to track and evaluate streaming applications.
As an example, below is an Llama-Index query engine with streaming.
"},{"location":"trulens_eval/llama_index_quickstart/","title":"Llama-Index Quickstart","text":"In\u00a0[\u00a0]: Copied!
# pip install trulens-eval==0.17.0 llama_index>=0.8.29post1 html2text>=2020.1.16\n
# pip install trulens-eval==0.17.0 llama_index>=0.8.29post1 html2text>=2020.1.16 In\u00a0[\u00a0]: Copied!
import os\nos.environ[\"OPENAI_API_KEY\"] = \"...\"\n
import os os.environ[\"OPENAI_API_KEY\"] = \"...\" In\u00a0[\u00a0]: Copied!
from trulens_eval import Feedback, Tru, TruLlama\nfrom trulens_eval.feedback import Groundedness\nfrom trulens_eval.feedback.provider.openai import OpenAI\n\ntru = Tru()\n
from trulens_eval import Feedback, Tru, TruLlama from trulens_eval.feedback import Groundedness from trulens_eval.feedback.provider.openai import OpenAI tru = Tru() In\u00a0[\u00a0]: Copied!
from llama_index import VectorStoreIndex, SimpleWebPageReader\n\ndocuments = SimpleWebPageReader(\n html_to_text=True\n).load_data([\"http://paulgraham.com/worked.html\"])\nindex = VectorStoreIndex.from_documents(documents)\n\nquery_engine = index.as_query_engine()\n
from llama_index import VectorStoreIndex, SimpleWebPageReader documents = SimpleWebPageReader( html_to_text=True ).load_data([\"http://paulgraham.com/worked.html\"]) index = VectorStoreIndex.from_documents(documents) query_engine = index.as_query_engine() In\u00a0[\u00a0]: Copied!
response = query_engine.query(\"What did the author do growing up?\")\nprint(response)\n
response = query_engine.query(\"What did the author do growing up?\") print(response) In\u00a0[\u00a0]: Copied!
import numpy as np\n\n# Initialize provider class\nopenai = OpenAI()\n\ngrounded = Groundedness(groundedness_provider=OpenAI())\n\n# Define a groundedness feedback function\nf_groundedness = Feedback(grounded.groundedness_measure_with_cot_reasons).on(\n TruLlama.select_source_nodes().node.text\n ).on_output(\n ).aggregate(grounded.grounded_statements_aggregator)\n\n# Question/answer relevance between overall question and answer.\nf_qa_relevance = Feedback(openai.relevance).on_input_output()\n\n# Question/statement relevance between question and each context chunk.\nf_qs_relevance = Feedback(openai.qs_relevance).on_input().on(\n TruLlama.select_source_nodes().node.text\n ).aggregate(np.mean)\n
import numpy as np # Initialize provider class openai = OpenAI() grounded = Groundedness(groundedness_provider=OpenAI()) # Define a groundedness feedback function f_groundedness = Feedback(grounded.groundedness_measure_with_cot_reasons).on( TruLlama.select_source_nodes().node.text ).on_output( ).aggregate(grounded.grounded_statements_aggregator) # Question/answer relevance between overall question and answer. f_qa_relevance = Feedback(openai.relevance).on_input_output() # Question/statement relevance between question and each context chunk. f_qs_relevance = Feedback(openai.qs_relevance).on_input().on( TruLlama.select_source_nodes().node.text ).aggregate(np.mean) In\u00a0[\u00a0]: Copied!
tru_query_engine_recorder = TruLlama(query_engine,\n app_id='LlamaIndex_App1',\n feedbacks=[f_groundedness, f_qa_relevance, f_qs_relevance])\n
tru_query_engine_recorder = TruLlama(query_engine, app_id='LlamaIndex_App1', feedbacks=[f_groundedness, f_qa_relevance, f_qs_relevance]) In\u00a0[\u00a0]: Copied!
# or as context manager\nwith tru_query_engine_recorder as recording:\n query_engine.query(\"What did the author do growing up?\")\n
# or as context manager with tru_query_engine_recorder as recording: query_engine.query(\"What did the author do growing up?\") In\u00a0[\u00a0]: Copied!
tru.run_dashboard() # open a local streamlit app to explore\n\n# tru.stop_dashboard() # stop if needed\n
tru.run_dashboard() # open a local streamlit app to explore # tru.stop_dashboard() # stop if needed
Alternatively, you can run trulens-eval from a command line in the same folder to start the dashboard.
Note: Feedback functions evaluated in the deferred manner can be seen in the \"Progress\" page of the TruLens dashboard.
In\u00a0[\u00a0]: Copied!
tru.get_records_and_feedback(app_ids=[])[0] # pass an empty list of app_ids to get all\n
tru.get_records_and_feedback(app_ids=[])[0] # pass an empty list of app_ids to get all"},{"location":"trulens_eval/llama_index_quickstart/#llama-index-quickstart","title":"Llama-Index Quickstart\u00b6","text":"
In this quickstart you will create a simple Llama Index App and learn how to log it and get feedback on an LLM response.
For evaluation, we will leverage the \"hallucination triad\" of groundedness, context relevance and answer relevance.
"},{"location":"trulens_eval/llama_index_quickstart/#setup","title":"Setup\u00b6","text":""},{"location":"trulens_eval/llama_index_quickstart/#install-dependencies","title":"Install dependencies\u00b6","text":"
Let's install some of the dependencies for this notebook if we don't have them already
"},{"location":"trulens_eval/llama_index_quickstart/#add-api-keys","title":"Add API keys\u00b6","text":"
For this quickstart, you will need Open AI and Huggingface keys. The OpenAI key is used for embeddings and GPT, and the Huggingface key is used for evaluation.
"},{"location":"trulens_eval/llama_index_quickstart/#import-from-llamaindex-and-trulens","title":"Import from LlamaIndex and TruLens\u00b6","text":""},{"location":"trulens_eval/llama_index_quickstart/#create-simple-llm-application","title":"Create Simple LLM Application\u00b6","text":"
This example uses LlamaIndex which internally uses an OpenAI LLM.
"},{"location":"trulens_eval/llama_index_quickstart/#send-your-first-request","title":"Send your first request\u00b6","text":""},{"location":"trulens_eval/llama_index_quickstart/#initialize-feedback-functions","title":"Initialize Feedback Function(s)\u00b6","text":""},{"location":"trulens_eval/llama_index_quickstart/#instrument-app-for-logging-with-trulens","title":"Instrument app for logging with TruLens\u00b6","text":""},{"location":"trulens_eval/llama_index_quickstart/#explore-in-a-dashboard","title":"Explore in a Dashboard\u00b6","text":""},{"location":"trulens_eval/llama_index_quickstart/#or-view-results-directly-in-your-notebook","title":"Or view results directly in your notebook\u00b6","text":""},{"location":"trulens_eval/logging/","title":"Logging Methods","text":"In\u00a0[\u00a0]: Copied!
truchain = TruChain(\n chain,\n app_id='Chain1_ChatApplication',\n tru=tru\n)\ntruchain(\"This will be automatically logged.\")\n
truchain = TruChain( chain, app_id='Chain1_ChatApplication', tru=tru ) truchain(\"This will be automatically logged.\")
Feedback functions can also be logged automatically by providing them in a list to the feedbacks arg.
In\u00a0[\u00a0]: Copied!
truchain = TruChain(\n chain,\n app_id='Chain1_ChatApplication',\n feedbacks=[f_lang_match], # feedback functions\n tru=tru\n)\ntruchain(\"This will be automatically logged.\")\n
truchain = TruChain( chain, app_id='Chain1_ChatApplication', feedbacks=[f_lang_match], # feedback functions tru=tru ) truchain(\"This will be automatically logged.\") In\u00a0[\u00a0]: Copied!
tc = TruChain(chain, app_id='Chain1_ChatApplication')\n
tc = TruChain(chain, app_id='Chain1_ChatApplication') In\u00a0[\u00a0]: Copied!
prompt_input = 'que hora es?'\ngpt3_response, record = tc.call_with_record(prompt_input)\n
prompt_input = 'que hora es?' gpt3_response, record = tc.call_with_record(prompt_input)
We can log the records but first we need to log the chain itself.
In\u00a0[\u00a0]: Copied!
tru.add_app(app=truchain)\n
tru.add_app(app=truchain)
Then we can log the record:
In\u00a0[\u00a0]: Copied!
tru.add_record(record)\n
tru.add_record(record) In\u00a0[\u00a0]: Copied!
thumb_result = True\ntru.add_feedback(name=\"\ud83d\udc4d (1) or \ud83d\udc4e (0)\", \n record_id=record.record_id, \n result=thumb_result)\n
thumb_result = True tru.add_feedback(name=\"\ud83d\udc4d (1) or \ud83d\udc4e (0)\", record_id=record.record_id, result=thumb_result) In\u00a0[\u00a0]: Copied!
feedback_results = tru.run_feedback_functions(\n record=record,\n feedback_functions=[f_lang_match]\n)\ndisplay(feedback_results)\n
feedback_results = tru.run_feedback_functions( record=record, feedback_functions=[f_lang_match] ) display(feedback_results)
After capturing feedback, you can then log it to your local database.
In\u00a0[\u00a0]: Copied!
tru.add_feedbacks(feedback_results)\n
tru.add_feedbacks(feedback_results) In\u00a0[\u00a0]: Copied!
truchain: TruChain = TruChain(\n chain,\n app_id='Chain1_ChatApplication',\n feedbacks=[f_lang_match],\n tru=tru,\n feedback_mode=\"deferred\"\n)\n\ntru.start_evaluator()\ntruchain(\"This will be logged by deferred evaluator.\")\ntru.stop_evaluator()\n
truchain: TruChain = TruChain( chain, app_id='Chain1_ChatApplication', feedbacks=[f_lang_match], tru=tru, feedback_mode=\"deferred\" ) tru.start_evaluator() truchain(\"This will be logged by deferred evaluator.\") tru.stop_evaluator()"},{"location":"trulens_eval/logging/#logging-methods","title":"Logging Methods\u00b6","text":""},{"location":"trulens_eval/logging/#automatic-logging","title":"Automatic Logging\u00b6","text":"
The simplest method for logging with TruLens is by wrapping with TruChain and including the tru argument, as shown in the quickstart.
This is done like so:
"},{"location":"trulens_eval/logging/#manual-logging","title":"Manual Logging\u00b6","text":""},{"location":"trulens_eval/logging/#wrap-with-truchain-to-instrument-your-chain","title":"Wrap with TruChain to instrument your chain\u00b6","text":""},{"location":"trulens_eval/logging/#set-up-logging-and-instrumentation","title":"Set up logging and instrumentation\u00b6","text":"
Making the first call to your wrapped LLM Application will now also produce a log or \"record\" of the chain execution.
"},{"location":"trulens_eval/logging/#log-app-feedback","title":"Log App Feedback\u00b6","text":"
Capturing app feedback such as user feedback of the responses can be added with one call.
"},{"location":"trulens_eval/logging/#evaluate-quality","title":"Evaluate Quality\u00b6","text":"
Following the request to your app, you can then evaluate LLM quality using feedback functions. This is completed in a sequential call to minimize latency for your application, and evaluations will also be logged to your local machine.
To get feedback on the quality of your LLM, you can use any of the provided feedback functions or add your own.
To assess your LLM quality, you can provide the feedback functions to tru.run_feedback() in a list provided to feedback_functions.
"},{"location":"trulens_eval/logging/#out-of-band-feedback-evaluation","title":"Out-of-band Feedback evaluation\u00b6","text":"
In the above example, the feedback function evaluation is done in the same process as the chain evaluation. The alternative approach is the use the provided persistent evaluator started via tru.start_deferred_feedback_evaluator. Then specify the feedback_mode for TruChain as deferred to let the evaluator handle the feedback functions.
For demonstration purposes, we start the evaluator here but it can be started in another process.
"},{"location":"trulens_eval/text2text_quickstart/","title":"Text to Text Quickstart","text":"In\u00a0[\u00a0]: Copied!
# ! pip install trulens_eval==0.17.0\n
# ! pip install trulens_eval==0.17.0 In\u00a0[\u00a0]: Copied!
import os\nos.environ[\"OPENAI_API_KEY\"] = \"...\"\nos.environ[\"HUGGINGFACE_API_KEY\"] = \"...\"\n
import os os.environ[\"OPENAI_API_KEY\"] = \"...\" os.environ[\"HUGGINGFACE_API_KEY\"] = \"...\" In\u00a0[\u00a0]: Copied!
import openai\nopenai.api_key = os.environ[\"OPENAI_API_KEY\"]\n
import openai openai.api_key = os.environ[\"OPENAI_API_KEY\"] In\u00a0[\u00a0]: Copied!
from IPython.display import JSON\n\n# Imports main tools:\nfrom trulens_eval import Feedback, Huggingface, Tru\ntru = Tru()\n
from IPython.display import JSON # Imports main tools: from trulens_eval import Feedback, Huggingface, Tru tru = Tru() In\u00a0[\u00a0]: Copied!
def llm_standalone(prompt):\n return openai.ChatCompletion.create(\n model=\"gpt-3.5-turbo\",\n messages=[\n {\"role\": \"system\", \"content\": \"You are a question and answer bot, and you answer super upbeat.\"},\n {\"role\": \"user\", \"content\": prompt}\n ]\n )[\"choices\"][0][\"message\"][\"content\"]\n def llm_standalone(prompt): return openai.ChatCompletion.create( model=\"gpt-3.5-turbo\", messages=[ {\"role\": \"system\", \"content\": \"You are a question and answer bot, and you answer super upbeat.\"}, {\"role\": \"user\", \"content\": prompt} ] )[\"choices\"][0][\"message\"][\"content\"] In\u00a0[\u00a0]: Copied!
import hashlib\ndef simple_hash_callable(prompt):\n h = hashlib.shake_256(prompt.encode('utf-8'))\n return str(h.hexdigest(20))\n import hashlib def simple_hash_callable(prompt): h = hashlib.shake_256(prompt.encode('utf-8')) return str(h.hexdigest(20)) In\u00a0[\u00a0]: Copied!
prompt_input=\"How good is language AI?\"\nprompt_output = llm_standalone(prompt_input)\nprompt_output\n
prompt_input=\"How good is language AI?\" prompt_output = llm_standalone(prompt_input) prompt_output In\u00a0[\u00a0]: Copied!
simple_hash_callable(prompt_input)\n
simple_hash_callable(prompt_input) In\u00a0[\u00a0]: Copied!
# Initialize Huggingface-based feedback function collection class:\nhugs = Huggingface()\n\n# Define a sentiment feedback function using HuggingFace.\nf_sentiment = Feedback(hugs.positive_sentiment).on_output()\n
# Initialize Huggingface-based feedback function collection class: hugs = Huggingface() # Define a sentiment feedback function using HuggingFace. f_sentiment = Feedback(hugs.positive_sentiment).on_output() In\u00a0[\u00a0]: Copied!
from trulens_eval import TruBasicApp\ntru_llm_standalone_recorder = TruBasicApp(llm_standalone, app_id=\"Happy Bot\", feedbacks=[f_sentiment])\ntru_simple_hash_callable_recorder = TruBasicApp(simple_hash_callable, app_id=\"Hasher\", feedbacks=[f_sentiment])\n
from trulens_eval import TruBasicApp tru_llm_standalone_recorder = TruBasicApp(llm_standalone, app_id=\"Happy Bot\", feedbacks=[f_sentiment]) tru_simple_hash_callable_recorder = TruBasicApp(simple_hash_callable, app_id=\"Hasher\", feedbacks=[f_sentiment]) In\u00a0[\u00a0]: Copied!
with tru_llm_standalone_recorder as recording:\n tru_llm_standalone_recorder.app(prompt_input)\n
with tru_llm_standalone_recorder as recording: tru_llm_standalone_recorder.app(prompt_input) In\u00a0[\u00a0]: Copied!
with tru_simple_hash_callable_recorder as recording:\n tru_simple_hash_callable_recorder.app(prompt_input)\n
with tru_simple_hash_callable_recorder as recording: tru_simple_hash_callable_recorder.app(prompt_input) In\u00a0[\u00a0]: Copied!
tru.run_dashboard() # open a local streamlit app to explore\n\n# tru.stop_dashboard() # stop if needed\n
tru.run_dashboard() # open a local streamlit app to explore # tru.stop_dashboard() # stop if needed
Alternatively, you can run trulens-eval from a command line in the same folder to start the dashboard.
In\u00a0[\u00a0]: Copied!
tru.get_records_and_feedback(app_ids=[])[0] # pass an empty list of app_ids to get all\n
tru.get_records_and_feedback(app_ids=[])[0] # pass an empty list of app_ids to get all"},{"location":"trulens_eval/text2text_quickstart/#text-to-text-quickstart","title":"Text to Text Quickstart\u00b6","text":"
In this quickstart you will create a simple text to text application and learn how to log it and get feedback.
"},{"location":"trulens_eval/text2text_quickstart/#setup","title":"Setup\u00b6","text":""},{"location":"trulens_eval/text2text_quickstart/#add-api-keys","title":"Add API keys\u00b6","text":"
For this quickstart you will need Open AI and Huggingface keys
"},{"location":"trulens_eval/text2text_quickstart/#import-from-trulens","title":"Import from TruLens\u00b6","text":""},{"location":"trulens_eval/text2text_quickstart/#create-simple-text-to-text-application","title":"Create Simple Text to Text Application\u00b6","text":"
This example uses a bare bones OpenAI LLM, and a non-LLM just for demonstration purposes.
"},{"location":"trulens_eval/text2text_quickstart/#send-your-first-request","title":"Send your first request\u00b6","text":""},{"location":"trulens_eval/text2text_quickstart/#initialize-feedback-functions","title":"Initialize Feedback Function(s)\u00b6","text":""},{"location":"trulens_eval/text2text_quickstart/#instrument-the-callable-for-logging-with-trulens","title":"Instrument the callable for logging with TruLens\u00b6","text":""},{"location":"trulens_eval/text2text_quickstart/#explore-in-a-dashboard","title":"Explore in a Dashboard\u00b6","text":""},{"location":"trulens_eval/text2text_quickstart/#or-view-results-directly-in-your-notebook","title":"Or view results directly in your notebook\u00b6","text":""},{"location":"trulens_eval/use_cases_agent/","title":"TruLens for LLM Agents","text":"
This section highlights different end-to-end use cases that TruLens can help with when building LLM agent applications. For each use case, we not only motivate the use case but also discuss which components are most helpful for solving that use case.
Validate LLM Agent Actions
Verify that your agent uses the intended tools and check it against business requirements.
Detect LLM Agent Tool Gaps/Drift
Identify when your LLM agent is missing the tools it needs to complete the tasks required.
"},{"location":"trulens_eval/use_cases_any/","title":"TruLens for any application","text":"
This section highlights different end-to-end use cases that TruLens can help with for any LLM application. For each use case, we not only motivate the use case but also discuss which components are most helpful for solving that use case.
Model Selection
Use TruLens to choose the most performant and efficient model for your application.
Moderation and Safety
Monitor your LLM application responses against a set of moderation and safety checks.
Language Verification
Verify your LLM application responds in the same language it is prompted.
PII Detection
Verify your LLM application responds in the same language it is prompted.
"},{"location":"trulens_eval/use_cases_production/","title":"Moving apps from dev to prod","text":"
This section highlights different end-to-end use cases that TruLens can help with. For each use case, we not only motivate the use case but also discuss which components are most helpful for solving that use case.
Async Evaluation
Evaluate your applications that leverage async mode.
Deferred Evaluation
Defer evaluations to off-peak times.
Using AzureOpenAI
Use AzureOpenAI to run feedback functions.
Using AWS Bedrock
Use AWS Bedrock to run feedback functions.
"},{"location":"trulens_eval/use_cases_rag/","title":"For Retrieval Augmented Generation (RAG)","text":"
This section highlights different end-to-end use cases that TruLens can help with when building RAG applications. For each use case, we not only motivate the use case but also discuss which components are most helpful for solving that use case.
Detect and Mitigate Hallucination
Use groundedness feedback to ensure that your LLM responds using only the information retrieved from a verified knowledge source.
Improve Retrieval Quality
Measure and identify ways to improve the quality of retrieval for your RAG.
Optimize App Configuration
Iterate through a set of configuration options for your RAG including different metrics, parameters, models and more; find the most performant with TruLens.
Verify the Summarization Quality
Ensure that LLM summarizations contain the key points from source documents.
"},{"location":"trulens_eval/where_to_log/","title":"Where to Log","text":"
By default, all data is logged to the current working directory to default.sqlite (sqlite:///default.sqlite). Data can be logged to a SQLAlchemy-compatible referred to by database_url in the format dialect+driver://username:password@host:port/database.
See this article for more details on SQLAlchemy database URLs.
For example, for Postgres database trulens running on localhost with username trulensuser and password password set up a connection like so.
from trulens_eval import Tru\ntru = Tru(database_url=\"postgresql://trulensuser:password@localhost/trulens\")\n
After which you should receive the following message:
\ud83e\udd91 Tru initialized with db url postgresql://trulensuser:password@localhost/trulens.\n
"},{"location":"trulens_eval/api/appdefinition/","title":"App Definition","text":"
Bases: SerialModel, WithClassInfo
Source code in
trulens_eval/trulens_eval/schema.py class AppDefinition(SerialModel, WithClassInfo):\n # Serialized fields here whereas app.py:App contains\n # non-serialized fields.\n\n class Config:\n arbitrary_types_allowed = True\n\n app_id: AppID\n tags: Tags\n metadata: Metadata # TODO: rename to meta for consistency with other metas\n\n # Feedback functions to evaluate on each record. Unlike the above, these are\n # meant to be serialized.\n feedback_definitions: Sequence[FeedbackDefinition] = []\n\n # NOTE: Custom feedback functions cannot be run deferred and will be run as\n # if \"withappthread\" was set.\n feedback_mode: FeedbackMode = FeedbackMode.WITH_APP_THREAD\n\n # Class of the main instrumented object.\n root_class: Class # TODO: make classvar\n\n # App's main method. To be filled in by subclass. Want to make this abstract\n # but this causes problems when trying to load an AppDefinition from json.\n root_callable: ClassVar[FunctionOrMethod]\n\n # Wrapped app in jsonized form.\n app: JSON\n\n # EXPERIMENTAL\n # NOTE: temporary unsafe serialization of function that loads the app:\n # Dump of the initial app before any invocations. Can be used to create a new session.\n initial_app_loader_dump: Optional[SerialBytes] = None\n\n # Info to store about the app and to display in dashboard. This is useful if\n # app itself cannot be serialized. `app_extra_json`, then, can stand in place for\n # whatever the user might want to see about the app.\n app_extra_json: JSON\n\n @staticmethod\n def continue_session(\n app_definition_json: JSON, app: Any\n ) -> 'AppDefinition':\n # initial_app_loader: Optional[Callable] = None) -> 'AppDefinition':\n \"\"\"\n Create a copy of the json serialized app with the enclosed app being\n initialized to its initial state before any records are produced (i.e.\n blank memory).\n \"\"\"\n\n app_definition_json['app'] = app\n\n cls = WithClassInfo.get_class(app_definition_json)\n\n return cls(**app_definition_json)\n\n @staticmethod\n def new_session(\n app_definition_json: JSON,\n initial_app_loader: Optional[Callable] = None\n ) -> 'AppDefinition':\n \"\"\"\n Create a copy of the json serialized app with the enclosed app being\n initialized to its initial state before any records are produced (i.e.\n blank memory).\n \"\"\"\n\n serial_bytes_json: Optional[JSON] = app_definition_json[\n 'initial_app_loader_dump']\n\n if initial_app_loader is None:\n assert serial_bytes_json is not None, \"Cannot create new session without `initial_app_loader`.\"\n\n serial_bytes = SerialBytes.parse_obj(serial_bytes_json)\n\n app = dill.loads(serial_bytes.data)()\n\n else:\n app = initial_app_loader()\n data = dill.dumps(initial_app_loader, recurse=True)\n serial_bytes = SerialBytes(data=data)\n serial_bytes_json = serial_bytes.dict()\n\n app_definition_json['app'] = app\n app_definition_json['initial_app_loader_dump'] = serial_bytes_json\n\n cls: Type[App] = WithClassInfo.get_class(app_definition_json)\n\n return cls.parse_obj(app_definition_json)\n\n def jsonify_extra(self, content):\n # Called by jsonify for us to add any data we might want to add to the\n # serialization of `app`.\n if self.app_extra_json is not None:\n content['app'].update(self.app_extra_json)\n\n return content\n\n def __init__(\n self,\n app_id: Optional[AppID] = None,\n tags: Optional[Tags] = None,\n metadata: Optional[Metadata] = None,\n feedback_mode: FeedbackMode = FeedbackMode.WITH_APP_THREAD,\n app_extra_json: JSON = None,\n **kwargs\n ):\n\n # for us:\n kwargs['app_id'] = \"temporary\" # will be adjusted below\n kwargs['feedback_mode'] = feedback_mode\n kwargs['tags'] = \"\"\n kwargs['metadata'] = {}\n kwargs['app_extra_json'] = app_extra_json or dict()\n\n # for WithClassInfo:\n kwargs['obj'] = self\n\n super().__init__(**kwargs)\n\n if app_id is None:\n app_id = obj_id_of_obj(obj=self.dict(), prefix=\"app\")\n\n self.app_id = app_id\n\n if tags is None:\n tags = \"-\" # Set tags to a \"-\" if None is provided\n self.tags = tags\n\n if metadata is None:\n metadata = {}\n self.metadata = metadata\n\n # EXPERIMENTAL\n if 'initial_app_loader' in kwargs:\n try:\n dump = dill.dumps(kwargs['initial_app_loader'], recurse=True)\n\n if len(dump) > MAX_DILL_SIZE:\n logger.warning(\n f\"`initial_app_loader` dump is too big ({humanize.naturalsize(len(dump))} > {humanize.naturaldate(MAX_DILL_SIZE)} bytes). \"\n \"If you are loading large objects, include the loading logic inside `initial_app_loader`.\"\n )\n else:\n self.initial_app_loader_dump = SerialBytes(data=dump)\n\n # This is an older serialization approach that saved things\n # in local files instead of the DB. Leaving here for now as\n # serialization of large apps might make this necessary\n # again.\n \"\"\"\n path_json = Path.cwd() / f\"{app_id}.json\"\n path_dill = Path.cwd() / f\"{app_id}.dill\"\n\n with path_json.open(\"w\") as fh:\n fh.write(json_str_of_obj(self))\n\n with path_dill.open(\"wb\") as fh:\n fh.write(dump)\n\n print(f\"Wrote loadable app to {path_json} and {path_dill}.\")\n \"\"\"\n\n except Exception as e:\n logger.warning(\n f\"Could not serialize app loader. \"\n f\"Some trulens features may not be available: {e}\"\n )\n\n @staticmethod\n def get_loadable_apps():\n # EXPERIMENTAL\n \"\"\"\n Gets a list of all of the loadable apps. This is those that have\n `initial_app_loader_dump` set.\n \"\"\"\n\n rets = []\n\n from trulens_eval import Tru\n\n tru = Tru()\n\n apps = tru.get_apps()\n for app in apps:\n dump = app['initial_app_loader_dump']\n if dump is not None:\n rets.append(app)\n\n return rets\n\n def dict(self):\n return jsonify(self)\n\n @classmethod\n def select_inputs(cls) -> JSONPath:\n \"\"\"\n Get the path to the main app's call inputs.\n \"\"\"\n\n return getattr(\n Select.RecordCalls,\n cls.root_callable.default_factory().name\n ).args\n\n @classmethod\n def select_outputs(cls) -> JSONPath:\n \"\"\"\n Get the path to the main app's call outputs.\n \"\"\"\n\n return getattr(\n Select.RecordCalls,\n cls.root_callable.default_factory().name\n ).rets\n
"},{"location":"trulens_eval/api/appdefinition/#trulens_eval.trulens_eval.schema.AppDefinition.continue_session","title":"
continue_session(app_definition_json, app) staticmethod","text":"
Create a copy of the json serialized app with the enclosed app being initialized to its initial state before any records are produced (i.e. blank memory).
Source code in
trulens_eval/trulens_eval/schema.py @staticmethod\ndef continue_session(\n app_definition_json: JSON, app: Any\n) -> 'AppDefinition':\n # initial_app_loader: Optional[Callable] = None) -> 'AppDefinition':\n \"\"\"\n Create a copy of the json serialized app with the enclosed app being\n initialized to its initial state before any records are produced (i.e.\n blank memory).\n \"\"\"\n\n app_definition_json['app'] = app\n\n cls = WithClassInfo.get_class(app_definition_json)\n\n return cls(**app_definition_json)\n
"},{"location":"trulens_eval/api/appdefinition/#trulens_eval.trulens_eval.schema.AppDefinition.get_loadable_apps","title":"
get_loadable_apps() staticmethod","text":"
Gets a list of all of the loadable apps. This is those that have initial_app_loader_dump set.
Source code in
trulens_eval/trulens_eval/schema.py @staticmethod\ndef get_loadable_apps():\n # EXPERIMENTAL\n \"\"\"\n Gets a list of all of the loadable apps. This is those that have\n `initial_app_loader_dump` set.\n \"\"\"\n\n rets = []\n\n from trulens_eval import Tru\n\n tru = Tru()\n\n apps = tru.get_apps()\n for app in apps:\n dump = app['initial_app_loader_dump']\n if dump is not None:\n rets.append(app)\n\n return rets\n
"},{"location":"trulens_eval/api/appdefinition/#trulens_eval.trulens_eval.schema.AppDefinition.new_session","title":"
new_session(app_definition_json, initial_app_loader=None) staticmethod","text":"
Create a copy of the json serialized app with the enclosed app being initialized to its initial state before any records are produced (i.e. blank memory).
Source code in
trulens_eval/trulens_eval/schema.py @staticmethod\ndef new_session(\n app_definition_json: JSON,\n initial_app_loader: Optional[Callable] = None\n) -> 'AppDefinition':\n \"\"\"\n Create a copy of the json serialized app with the enclosed app being\n initialized to its initial state before any records are produced (i.e.\n blank memory).\n \"\"\"\n\n serial_bytes_json: Optional[JSON] = app_definition_json[\n 'initial_app_loader_dump']\n\n if initial_app_loader is None:\n assert serial_bytes_json is not None, \"Cannot create new session without `initial_app_loader`.\"\n\n serial_bytes = SerialBytes.parse_obj(serial_bytes_json)\n\n app = dill.loads(serial_bytes.data)()\n\n else:\n app = initial_app_loader()\n data = dill.dumps(initial_app_loader, recurse=True)\n serial_bytes = SerialBytes(data=data)\n serial_bytes_json = serial_bytes.dict()\n\n app_definition_json['app'] = app\n app_definition_json['initial_app_loader_dump'] = serial_bytes_json\n\n cls: Type[App] = WithClassInfo.get_class(app_definition_json)\n\n return cls.parse_obj(app_definition_json)\n
"},{"location":"trulens_eval/api/appdefinition/#trulens_eval.trulens_eval.schema.AppDefinition.select_inputs","title":"
select_inputs() classmethod","text":"
Get the path to the main app's call inputs.
Source code in
trulens_eval/trulens_eval/schema.py @classmethod\ndef select_inputs(cls) -> JSONPath:\n \"\"\"\n Get the path to the main app's call inputs.\n \"\"\"\n\n return getattr(\n Select.RecordCalls,\n cls.root_callable.default_factory().name\n ).args\n
"},{"location":"trulens_eval/api/appdefinition/#trulens_eval.trulens_eval.schema.AppDefinition.select_outputs","title":"
select_outputs() classmethod","text":"
Get the path to the main app's call outputs.
Source code in
trulens_eval/trulens_eval/schema.py @classmethod\ndef select_outputs(cls) -> JSONPath:\n \"\"\"\n Get the path to the main app's call outputs.\n \"\"\"\n\n return getattr(\n Select.RecordCalls,\n cls.root_callable.default_factory().name\n ).rets\n
"},{"location":"trulens_eval/api/bedrock_provider/","title":"AWS Bedrock APIs","text":"
Below is how you can instantiate AWS Bedrock as a provider. Amazon Bedrock is a fully managed service that makes FMs from leading AI startups and Amazon available via an API, so you can choose from a wide range of FMs to find the model that is best suited for your use case
All feedback functions listed in the base LLMProvider class can be run with AWS Bedrock.
Bases: LLMProvider
Source code in
trulens_eval/trulens_eval/feedback/provider/bedrock.py class Bedrock(LLMProvider):\n model_id: str\n region_name: str\n\n def __init__(\n self,\n *args,\n model_id=\"amazon.titan-tg1-large\",\n region_name=\"us-east-1\",\n **kwargs\n ):\n # NOTE(piotrm): pydantic adds endpoint to the signature of this\n # constructor if we don't include it explicitly, even though we set it\n # down below. Adding it as None here as a temporary hack.\n \"\"\"\n A set of AWS Feedback Functions.\n\n Parameters:\n\n - model_id (str, optional): The specific model id. Defaults to\n \"amazon.titan-tg1-large\".\n - region_name (str, optional): The specific AWS region name. Defaults to\n \"us-east-1\"\n\n - All other args/kwargs passed to the boto3 client constructor.\n \"\"\"\n # TODO: why was self_kwargs required here independently of kwargs?\n self_kwargs = dict()\n self_kwargs.update(**kwargs)\n\n self_kwargs['model_id'] = model_id\n self_kwargs['region_name'] = region_name\n self_kwargs['endpoint'] = BedrockEndpoint(\n region_name=region_name, *args, **kwargs\n )\n\n super().__init__(\n **self_kwargs\n ) # need to include pydantic.BaseModel.__init__\n\n # LLMProvider requirement\n def _create_chat_completion(\n self,\n prompt: Optional[str] = None,\n messages: Optional[Sequence[Dict]] = None,\n **kwargs\n ) -> str:\n\n # NOTE(joshr): only tested with sso auth\n import json\n\n import boto3\n bedrock = boto3.client(service_name='bedrock-runtime')\n\n assert prompt is not None, \"Bedrock can only operate on `prompt`, not `messages`.\"\n\n body = json.dumps({\"inputText\": prompt})\n\n modelId = self.model_id\n\n response = bedrock.invoke_model(body=body, modelId=modelId)\n\n response_body = json.loads(response.get('body').read()\n ).get('results')[0][\"outputText\"]\n # text\n return response_body\n
"},{"location":"trulens_eval/api/bedrock_provider/#trulens_eval.trulens_eval.feedback.provider.bedrock.Bedrock.__init__","title":"
__init__(*args, model_id='amazon.titan-tg1-large', region_name='us-east-1', **kwargs)","text":"
A set of AWS Feedback Functions.
Parameters:
- model_id (str, optional): The specific model id. Defaults to \"amazon.titan-tg1-large\".
-
region_name (str, optional): The specific AWS region name. Defaults to \"us-east-1\"
-
All other args/kwargs passed to the boto3 client constructor.
Source code in
trulens_eval/trulens_eval/feedback/provider/bedrock.py def __init__(\n self,\n *args,\n model_id=\"amazon.titan-tg1-large\",\n region_name=\"us-east-1\",\n **kwargs\n):\n # NOTE(piotrm): pydantic adds endpoint to the signature of this\n # constructor if we don't include it explicitly, even though we set it\n # down below. Adding it as None here as a temporary hack.\n \"\"\"\n A set of AWS Feedback Functions.\n\n Parameters:\n\n - model_id (str, optional): The specific model id. Defaults to\n \"amazon.titan-tg1-large\".\n - region_name (str, optional): The specific AWS region name. Defaults to\n \"us-east-1\"\n\n - All other args/kwargs passed to the boto3 client constructor.\n \"\"\"\n # TODO: why was self_kwargs required here independently of kwargs?\n self_kwargs = dict()\n self_kwargs.update(**kwargs)\n\n self_kwargs['model_id'] = model_id\n self_kwargs['region_name'] = region_name\n self_kwargs['endpoint'] = BedrockEndpoint(\n region_name=region_name, *args, **kwargs\n )\n\n super().__init__(\n **self_kwargs\n ) # need to include pydantic.BaseModel.__init__\n
"},{"location":"trulens_eval/api/feedback/","title":"Feedback Function APIs","text":"
Below are out of the box feedback functions and how to instantiate them.
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider","title":"
LLMProvider","text":"
Bases: Provider, ABC
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py class LLMProvider(Provider, ABC):\n\n model_engine: str\n\n def __init__(self, *args, **kwargs):\n # NOTE(piotrm): pydantic adds endpoint to the signature of this\n # constructor if we don't include it explicitly, even though we set it\n # down below. Adding it as None here as a temporary hack\n\n # TODO: why was self_kwargs required here independently of kwargs?\n self_kwargs = dict()\n self_kwargs.update(**kwargs)\n\n super().__init__(\n **self_kwargs\n ) # need to include pydantic.BaseModel.__init__\n\n @abstractmethod\n def _create_chat_completion(\n self,\n prompt: Optional[str] = None,\n messages: Optional[Sequence[Dict]] = None,\n **kwargs\n ) -> str:\n \"\"\"\n Chat Completion Model\n\n Returns:\n str: Completion model response.\n \"\"\"\n # text\n pass\n\n def _find_relevant_string(self, full_source: str, hypothesis: str) -> str:\n return self.endpoint.run_me(\n lambda: self._create_chat_completion(\n prompt=str.format(\n prompts.SYSTEM_FIND_SUPPORTING,\n prompt=full_source,\n ) + \"\\n\" + str.\n format(prompts.USER_FIND_SUPPORTING, response=hypothesis)\n )\n )\n\n def _summarized_groundedness(self, premise: str, hypothesis: str) -> float:\n \"\"\"\n A groundedness measure best used for summarized premise against simple\n hypothesis. This LLM implementation uses information overlap prompts.\n\n Args:\n premise (str): Summarized source sentences.\n hypothesis (str): Single statement setnece.\n\n Returns:\n float: Information Overlap\n \"\"\"\n return re_0_10_rating(\n self.endpoint.run_me(\n lambda: self._create_chat_completion(\n prompt=str.format(\n prompts.LLM_GROUNDEDNESS,\n premise=premise,\n hypothesis=hypothesis,\n )\n )\n )\n ) / 10.0\n\n def _groundedness_doc_in_out(self, premise: str, hypothesis: str) -> str:\n \"\"\"\n An LLM prompt using the entire document for premise and entire statement\n document for hypothesis.\n\n Args:\n premise (str): A source document\n hypothesis (str): A statement to check\n\n Returns:\n str: An LLM response using a scorecard template\n \"\"\"\n return self.endpoint.run_me(\n lambda: self._create_chat_completion(\n prompt=str.format(prompts.LLM_GROUNDEDNESS_FULL_SYSTEM,) + str.\n format(\n prompts.LLM_GROUNDEDNESS_FULL_PROMPT,\n premise=premise,\n hypothesis=hypothesis\n )\n )\n )\n\n def _extract_score_and_reasons_from_response(\n self,\n system_prompt: str,\n user_prompt: Optional[str] = None,\n normalize: float = 10.0\n ) -> Union[float, Tuple[float, Dict]]:\n \"\"\"\n Extractor for our LLM prompts. If CoT is used; it will look for\n \"Supporting Evidence\" template. Otherwise, it will look for the typical\n 0-10 scoring.\n\n Args:\n system_prompt (str): A pre-formated system prompt\n\n Returns:\n The score and reason metadata if available.\n \"\"\"\n llm_messages = [{\"role\": \"system\", \"content\": system_prompt}]\n if user_prompt is not None:\n llm_messages.append({\"role\": \"user\", \"content\": user_prompt})\n\n response = self.endpoint.run_me(\n lambda: self._create_chat_completion(messages=llm_messages)\n )\n if \"Supporting Evidence\" in response:\n score = 0.0\n supporting_evidence = \"\"\n for line in response.split('\\n'):\n if \"Score\" in line:\n score = re_0_10_rating(line) / normalize\n if \"Criteria\" in line:\n parts = line.split(\":\")\n if len(parts) > 1:\n criteria = \":\".join(parts[1:]).strip()\n if \"Supporting Evidence\" in line:\n parts = line.split(\":\")\n if len(parts) > 1:\n supporting_evidence = \":\".join(parts[1:]).strip()\n reasons = {\n 'reason':\n (\n f\"{'Criteria: ' + str(criteria) + ' ' if criteria else ''}\\n\"\n f\"{'Supporting Evidence: ' + str(supporting_evidence) if supporting_evidence else ''}\"\n )\n }\n return score, reasons\n else:\n return re_0_10_rating(response) / normalize\n\n def qs_relevance(self, question: str, statement: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the relevance of the statement to the question.\n\n ```python\n feedback = Feedback(provider.qs_relevance).on_input_output() \n ```\n The `on_input_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Usage on RAG Contexts:\n\n ```python\n feedback = Feedback(provider.qs_relevance).on_input().on(\n TruLlama.select_source_nodes().node.text # See note below\n ).aggregate(np.mean) \n ```\n\n The `on(...)` selector can be changed. See [Feedback Function Guide :\n Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Args:\n question (str): A question being asked. \n statement (str): A statement to the question.\n\n Returns:\n float: A value between 0.0 (not relevant) and 1.0 (relevant).\n \"\"\"\n return re_0_10_rating(\n self.endpoint.run_me(\n lambda: self._create_chat_completion(\n prompt=str.format(\n prompts.QS_RELEVANCE,\n question=question,\n statement=statement\n )\n )\n )\n ) / 10\n\n def qs_relevance_with_cot_reasons(\n self, question: str, statement: str\n ) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a\n template to check the relevance of the statement to the question.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```\n feedback = Feedback(provider.qs_relevance_with_cot_reasons).on_input_output() \n ```\n The `on_input_output()` selector can be changed. See [Feedback Function Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Usage on RAG Contexts:\n ```\n feedback = Feedback(provider.qs_relevance_with_cot_reasons).on_input().on(\n TruLlama.select_source_nodes().node.text # See note below\n ).aggregate(np.mean) \n\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n\n Args:\n question (str): A question being asked. \n statement (str): A statement to the question.\n\n Returns:\n float: A value between 0 and 1. 0 being \"not relevant\" and 1 being \"relevant\".\n \"\"\"\n system_prompt = str.format(\n prompts.QS_RELEVANCE, question=question, statement=statement\n )\n system_prompt = system_prompt.replace(\n \"RELEVANCE:\", prompts.COT_REASONS_TEMPLATE\n )\n return self.endpoint.run_me(\n lambda: self.\n _extract_score_and_reasons_from_response(system_prompt)\n )\n\n def relevance(self, prompt: str, response: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a\n template to check the relevance of the response to a prompt.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.relevance).on_input_output()\n ```\n\n The `on_input_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Usage on RAG Contexts:\n\n ```python\n feedback = Feedback(provider.relevance).on_input().on(\n TruLlama.select_source_nodes().node.text # See note below\n ).aggregate(np.mean) \n ```\n\n The `on(...)` selector can be changed. See [Feedback Function Guide :\n Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Parameters:\n prompt (str): A text prompt to an agent.\n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0 and 1. 0 being \"not relevant\" and 1 being\n \"relevant\".\n \"\"\"\n return re_0_10_rating(\n self.endpoint.run_me(\n lambda: self._create_chat_completion(\n prompt=str.format(\n prompts.PR_RELEVANCE, prompt=prompt, response=response\n )\n )\n )\n ) / 10.0\n\n def relevance_with_cot_reasons(self, prompt: str, response: str) -> float:\n \"\"\"\n Uses chat completion Model. A function that completes a template to\n check the relevance of the response to a prompt. Also uses chain of\n thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.relevance_with_cot_reasons).on_input_output()\n ```\n\n The `on_input_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Usage on RAG Contexts:\n ```python\n\n feedback = Feedback(provider.relevance_with_cot_reasons).on_input().on(\n TruLlama.select_source_nodes().node.text # See note below\n ).aggregate(np.mean) \n ```\n\n The `on(...)` selector can be changed. See [Feedback Function Guide :\n Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Args:\n prompt (str): A text prompt to an agent. \n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0 and 1. 0 being \"not relevant\" and 1 being\n \"relevant\".\n \"\"\"\n system_prompt = str.format(\n prompts.PR_RELEVANCE, prompt=prompt, response=response\n )\n system_prompt = system_prompt.replace(\n \"RELEVANCE:\", prompts.COT_REASONS_TEMPLATE\n )\n return self._extract_score_and_reasons_from_response(system_prompt)\n\n def sentiment(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the sentiment of some text.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.sentiment).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Parameters:\n text (str): A prompt to an agent.\n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0 and 1. 0 being \"negative sentiment\" and 1\n being \"positive sentiment\".\n \"\"\"\n\n return re_0_10_rating(\n self.endpoint.run_me(\n lambda: self._create_chat_completion(\n prompt=prompts.SENTIMENT_SYSTEM_PROMPT + text\n )\n )\n ) / 10.0\n\n def sentiment_with_cot_reasons(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a\n template to check the sentiment of some text.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n\n ```python\n feedback = Feedback(provider.sentiment_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (negative sentiment) and 1.0 (positive sentiment).\n \"\"\"\n\n system_prompt = prompts.SENTIMENT_SYSTEM_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def model_agreement(self, prompt: str, response: str) -> float:\n \"\"\"\n Uses chat completion model. A function that gives a chat completion model the same\n prompt and gets a response, encouraging truthfulness. A second template\n is given to the model with a prompt that the original response is\n correct, and measures whether previous chat completion response is similar.\n\n **Usage:**\n\n ```python\n feedback = Feedback(provider.model_agreement).on_input_output() \n ```\n\n The `on_input_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Parameters:\n prompt (str): A text prompt to an agent.\n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0.0 (not in agreement) and 1.0 (in agreement).\n \"\"\"\n warnings.warn(\n \"`model_agreement` has been deprecated. \"\n \"Use `GroundTruthAgreement(ground_truth)` instead.\",\n DeprecationWarning\n )\n chat_response = self._create_chat_completion(\n prompt=prompts.CORRECT_SYSTEM_PROMPT\n )\n agreement_txt = self._get_answer_agreement(\n prompt, response, chat_response\n )\n return re_0_10_rating(agreement_txt) / 10.0\n\n # TODO: figure out where text is used.\n def _langchain_evaluate(self, text: str, system_prompt: str) -> float:\n \"\"\"\n Uses chat completion model. A general function that completes a template\n to evaluate different aspects of some text. Prompt credit to Langchain\n Eval.\n\n Parameters:\n text (str): A prompt to an agent.\n system_prompt (str): The specific system prompt for evaluation.\n\n Returns:\n float: A value between 0.0 and 1.0, representing the specified\n evaluation.\n \"\"\"\n\n return re_0_10_rating(\n self.endpoint.\n run_me(lambda: self._create_chat_completion(prompt=system_prompt))\n ) / 10.0\n\n def conciseness(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the conciseness of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n\n ```python\n feedback = Feedback(provider.conciseness).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Parameters:\n text (str): A prompt to an agent.\n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0.0 (not concise) and 1.0 (concise).\n \"\"\"\n return self._langchain_evaluate(\n text, prompts.LANGCHAIN_CONCISENESS_PROMPT\n )\n\n def correctness(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the correctness of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.correctness).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Parameters:\n text (str): A prompt to an agent. response (str): The agent's\n response to the prompt.\n\n Returns:\n float: A value between 0.0 (not correct) and 1.0 (correct).\n \"\"\"\n system_prompt = prompts.LANGCHAIN_CORRECTNESS_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def correctness_with_cot_reasons(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the correctness of some text. Prompt credit to Langchain Eval.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.correctness_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not correct) and 1.0 (correct).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_CORRECTNESS_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def coherence(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a\n template to check the coherence of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.coherence).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not coherent) and 1.0 (coherent).\n \"\"\"\n system_prompt = prompts.LANGCHAIN_COHERENCE_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def coherence_with_cot_reasons(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the coherence of some text. Prompt credit to Langchain Eval. Also\n uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.coherence_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not coherent) and 1.0 (coherent).\n \"\"\"\n system_prompt = prompts.LANGCHAIN_COHERENCE_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def harmfulness(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the harmfulness of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.harmfulness).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not harmful) and 1.0 (harmful)\".\n \"\"\"\n return self._langchain_evaluate(\n text, prompts.LANGCHAIN_HARMFULNESS_PROMPT\n )\n\n def harmfulness_with_cot_reasons(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the harmfulness of some text. Prompt credit to Langchain Eval.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.harmfulness_with_cot_reasons).on_output() \n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not harmful) and 1.0 (harmful).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_HARMFULNESS_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def maliciousness(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the maliciousness of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.maliciousness).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not malicious) and 1.0 (malicious).\n \"\"\"\n\n return self._langchain_evaluate(\n text, prompts.LANGCHAIN_MALICIOUSNESS_PROMPT\n )\n\n def maliciousness_with_cot_reasons(self, text: str) -> float:\n \"\"\"\n Uses chat compoletion model. A function that completes a\n template to check the maliciousness of some text. Prompt credit to Langchain Eval.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.maliciousness_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not malicious) and 1.0 (malicious).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_MALICIOUSNESS_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def helpfulness(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the helpfulness of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.helpfulness).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not helpful) and 1.0 (helpful).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_HELPFULNESS_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def helpfulness_with_cot_reasons(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the helpfulness of some text. Prompt credit to Langchain Eval.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.helpfulness_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.o (not helpful) and 1.0 (helpful).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_HELPFULNESS_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def controversiality(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the controversiality of some text. Prompt credit to Langchain\n Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.controversiality).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not controversial) and 1.0\n (controversial).\n \"\"\"\n system_prompt = prompts.LANGCHAIN_CONTROVERSIALITY_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def controversiality_with_cot_reasons(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the controversiality of some text. Prompt credit to Langchain\n Eval. Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.controversiality_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not controversial) and 1.0 (controversial).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_CONTROVERSIALITY_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def misogyny(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the misogyny of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.misogyny).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not misogynistic) and 1.0 (misogynistic).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_MISOGYNY_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def misogyny_with_cot_reasons(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the misogyny of some text. Prompt credit to Langchain Eval. Also\n uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.misogyny_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not misogynistic) and 1.0 (misogynistic).\n \"\"\"\n system_prompt = prompts.LANGCHAIN_MISOGYNY_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def criminality(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the criminality of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.criminality).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not criminal) and 1.0 (criminal).\n\n \"\"\"\n system_prompt = prompts.LANGCHAIN_CRIMINALITY_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def criminality_with_cot_reasons(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the criminality of some text. Prompt credit to Langchain Eval.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.criminality_with_cot_reasons).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not criminal) and 1.0 (criminal).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_CRIMINALITY_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def insensitivity(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the insensitivity of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.insensitivity).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not insensitive) and 1.0 (insensitive).\n \"\"\"\n system_prompt = prompts.LANGCHAIN_INSENSITIVITY_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def insensitivity_with_cot_reasons(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the insensitivity of some text. Prompt credit to Langchain Eval.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.insensitivity_with_cot_reasons).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not insensitive) and 1.0 (insensitive).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_INSENSITIVITY_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def _get_answer_agreement(\n self, prompt: str, response: str, check_response: str\n ) -> str:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check if two answers agree.\n\n Parameters:\n text (str): A prompt to an agent.\n response (str): The agent's response to the prompt.\n check_response(str): The response to check against.\n\n Returns:\n str\n \"\"\"\n\n return self.endpoint.run_me(\n lambda: self._create_chat_completion(\n prompt=(prompts.AGREEMENT_SYSTEM_PROMPT %\n (prompt, response)) + check_response\n )\n )\n\n def summary_with_cot_reasons(self, source: str, summary: str) -> float:\n \"\"\"\n Uses chat completion model. A function that tries to distill main points\n and compares a summary against those main points. This feedback function\n only has a chain of thought implementation as it is extremely important\n in function assessment.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.summary_with_cot_reasons).on_input_output()\n ```\n\n Args:\n source (str): Text corresponding to source material. \n summary (str): Text corresponding to a summary.\n\n Returns:\n float: A value between 0.0 (main points missed) and 1.0 (no main\n points missed).\n \"\"\"\n\n system_prompt = str.format(\n prompts.SUMMARIZATION_PROMPT, source=source, summary=summary\n )\n\n return self._extract_score_and_reasons_from_response(system_prompt)\n\n def stereotypes(self, prompt: str, response: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check adding assumed stereotypes in the response when not present in the\n prompt.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.stereotypes).on_input_output()\n ```\n\n Args:\n prompt (str): A text prompt to an agent. \n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0.0 (no stereotypes assumed) and 1.0\n (stereotypes assumed).\n \"\"\"\n\n system_prompt = str.format(\n prompts.STEREOTYPES_PROMPT, prompt=prompt, response=response\n )\n\n return self._extract_score_and_reasons_from_response(system_prompt)\n\n def stereotypes_with_cot_reasons(self, prompt: str, response: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check adding assumed stereotypes in the response when not present in the\n prompt.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.stereotypes).on_input_output()\n ```\n\n Args:\n prompt (str): A text prompt to an agent. \n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0.0 (no stereotypes assumed) and 1.0\n (stereotypes assumed).\n \"\"\"\n system_prompt = str.format(\n prompts.STEREOTYPES_PROMPT, prompt=prompt, response=response\n )\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n\n return self._extract_score_and_reasons_from_response(system_prompt)\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.coherence","title":"
coherence(text)","text":"
Uses chat completion model. A function that completes a template to check the coherence of some text. Prompt credit to Langchain Eval.
Usage:
feedback = Feedback(provider.coherence).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not coherent) and 1.0 (coherent).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def coherence(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a\n template to check the coherence of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.coherence).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not coherent) and 1.0 (coherent).\n \"\"\"\n system_prompt = prompts.LANGCHAIN_COHERENCE_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.coherence_with_cot_reasons","title":"
coherence_with_cot_reasons(text)","text":"
Uses chat completion model. A function that completes a template to check the coherence of some text. Prompt credit to Langchain Eval. Also uses chain of thought methodology and emits the reasons.
Usage:
feedback = Feedback(provider.coherence_with_cot_reasons).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not coherent) and 1.0 (coherent).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def coherence_with_cot_reasons(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the coherence of some text. Prompt credit to Langchain Eval. Also\n uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.coherence_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not coherent) and 1.0 (coherent).\n \"\"\"\n system_prompt = prompts.LANGCHAIN_COHERENCE_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.conciseness","title":"
conciseness(text)","text":"
Uses chat completion model. A function that completes a template to check the conciseness of some text. Prompt credit to Langchain Eval.
Usage:
feedback = Feedback(provider.conciseness).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str A prompt to an agent.
required
response str The agent's response to the prompt.
required
Returns:
Name Type Description
float float A value between 0.0 (not concise) and 1.0 (concise).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def conciseness(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the conciseness of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n\n ```python\n feedback = Feedback(provider.conciseness).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Parameters:\n text (str): A prompt to an agent.\n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0.0 (not concise) and 1.0 (concise).\n \"\"\"\n return self._langchain_evaluate(\n text, prompts.LANGCHAIN_CONCISENESS_PROMPT\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.controversiality","title":"
controversiality(text)","text":"
Uses chat completion model. A function that completes a template to check the controversiality of some text. Prompt credit to Langchain Eval.
Usage:
feedback = Feedback(provider.controversiality).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not controversial) and 1.0
float (controversial).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def controversiality(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the controversiality of some text. Prompt credit to Langchain\n Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.controversiality).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not controversial) and 1.0\n (controversial).\n \"\"\"\n system_prompt = prompts.LANGCHAIN_CONTROVERSIALITY_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.controversiality_with_cot_reasons","title":"
controversiality_with_cot_reasons(text)","text":"
Uses chat completion model. A function that completes a template to check the controversiality of some text. Prompt credit to Langchain Eval. Also uses chain of thought methodology and emits the reasons.
Usage:
feedback = Feedback(provider.controversiality_with_cot_reasons).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not controversial) and 1.0 (controversial).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def controversiality_with_cot_reasons(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the controversiality of some text. Prompt credit to Langchain\n Eval. Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.controversiality_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not controversial) and 1.0 (controversial).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_CONTROVERSIALITY_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.correctness","title":"
correctness(text)","text":"
Uses chat completion model. A function that completes a template to check the correctness of some text. Prompt credit to Langchain Eval.
Usage:
feedback = Feedback(provider.correctness).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str A prompt to an agent. response (str): The agent's
required
Returns:
Name Type Description
float float A value between 0.0 (not correct) and 1.0 (correct).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def correctness(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the correctness of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.correctness).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Parameters:\n text (str): A prompt to an agent. response (str): The agent's\n response to the prompt.\n\n Returns:\n float: A value between 0.0 (not correct) and 1.0 (correct).\n \"\"\"\n system_prompt = prompts.LANGCHAIN_CORRECTNESS_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.correctness_with_cot_reasons","title":"
correctness_with_cot_reasons(text)","text":"
Uses chat completion model. A function that completes a template to check the correctness of some text. Prompt credit to Langchain Eval. Also uses chain of thought methodology and emits the reasons.
Usage:
feedback = Feedback(provider.correctness_with_cot_reasons).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str Text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not correct) and 1.0 (correct).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def correctness_with_cot_reasons(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the correctness of some text. Prompt credit to Langchain Eval.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.correctness_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not correct) and 1.0 (correct).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_CORRECTNESS_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.criminality","title":"
criminality(text)","text":"
Uses chat completion model. A function that completes a template to check the criminality of some text. Prompt credit to Langchain Eval.
Usage:
feedback = Feedback(provider.criminality).on_output()\n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not criminal) and 1.0 (criminal).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def criminality(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the criminality of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.criminality).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not criminal) and 1.0 (criminal).\n\n \"\"\"\n system_prompt = prompts.LANGCHAIN_CRIMINALITY_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.criminality_with_cot_reasons","title":"
criminality_with_cot_reasons(text)","text":"
Uses chat completion model. A function that completes a template to check the criminality of some text. Prompt credit to Langchain Eval. Also uses chain of thought methodology and emits the reasons.
Usage:
feedback = Feedback(provider.criminality_with_cot_reasons).on_output()\n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not criminal) and 1.0 (criminal).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def criminality_with_cot_reasons(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the criminality of some text. Prompt credit to Langchain Eval.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.criminality_with_cot_reasons).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not criminal) and 1.0 (criminal).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_CRIMINALITY_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.harmfulness","title":"
harmfulness(text)","text":"
Uses chat completion model. A function that completes a template to check the harmfulness of some text. Prompt credit to Langchain Eval.
Usage:
feedback = Feedback(provider.harmfulness).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not harmful) and 1.0 (harmful)\".
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def harmfulness(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the harmfulness of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.harmfulness).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not harmful) and 1.0 (harmful)\".\n \"\"\"\n return self._langchain_evaluate(\n text, prompts.LANGCHAIN_HARMFULNESS_PROMPT\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.harmfulness_with_cot_reasons","title":"
harmfulness_with_cot_reasons(text)","text":"
Uses chat completion model. A function that completes a template to check the harmfulness of some text. Prompt credit to Langchain Eval. Also uses chain of thought methodology and emits the reasons.
Usage: ```python feedback = Feedback(provider.harmfulness_with_cot_reasons).on_output()
Args: text (str): The text to evaluate.
Returns: float: A value between 0.0 (not harmful) and 1.0 (harmful).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def harmfulness_with_cot_reasons(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the harmfulness of some text. Prompt credit to Langchain Eval.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.harmfulness_with_cot_reasons).on_output() \n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not harmful) and 1.0 (harmful).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_HARMFULNESS_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.helpfulness","title":"
helpfulness(text)","text":"
Uses chat completion model. A function that completes a template to check the helpfulness of some text. Prompt credit to Langchain Eval.
Usage:
feedback = Feedback(provider.helpfulness).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not helpful) and 1.0 (helpful).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def helpfulness(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the helpfulness of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.helpfulness).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not helpful) and 1.0 (helpful).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_HELPFULNESS_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.helpfulness_with_cot_reasons","title":"
helpfulness_with_cot_reasons(text)","text":"
Uses chat completion model. A function that completes a template to check the helpfulness of some text. Prompt credit to Langchain Eval. Also uses chain of thought methodology and emits the reasons.
Usage:
feedback = Feedback(provider.helpfulness_with_cot_reasons).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.o (not helpful) and 1.0 (helpful).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def helpfulness_with_cot_reasons(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the helpfulness of some text. Prompt credit to Langchain Eval.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.helpfulness_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.o (not helpful) and 1.0 (helpful).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_HELPFULNESS_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.insensitivity","title":"
insensitivity(text)","text":"
Uses chat completion model. A function that completes a template to check the insensitivity of some text. Prompt credit to Langchain Eval.
Usage:
feedback = Feedback(provider.insensitivity).on_output()\n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not insensitive) and 1.0 (insensitive).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def insensitivity(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the insensitivity of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.insensitivity).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not insensitive) and 1.0 (insensitive).\n \"\"\"\n system_prompt = prompts.LANGCHAIN_INSENSITIVITY_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.insensitivity_with_cot_reasons","title":"
insensitivity_with_cot_reasons(text)","text":"
Uses chat completion model. A function that completes a template to check the insensitivity of some text. Prompt credit to Langchain Eval. Also uses chain of thought methodology and emits the reasons.
Usage:
feedback = Feedback(provider.insensitivity_with_cot_reasons).on_output()\n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not insensitive) and 1.0 (insensitive).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def insensitivity_with_cot_reasons(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the insensitivity of some text. Prompt credit to Langchain Eval.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.insensitivity_with_cot_reasons).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not insensitive) and 1.0 (insensitive).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_INSENSITIVITY_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.maliciousness","title":"
maliciousness(text)","text":"
Uses chat completion model. A function that completes a template to check the maliciousness of some text. Prompt credit to Langchain Eval.
Usage:
feedback = Feedback(provider.maliciousness).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not malicious) and 1.0 (malicious).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def maliciousness(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the maliciousness of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.maliciousness).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not malicious) and 1.0 (malicious).\n \"\"\"\n\n return self._langchain_evaluate(\n text, prompts.LANGCHAIN_MALICIOUSNESS_PROMPT\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.maliciousness_with_cot_reasons","title":"
maliciousness_with_cot_reasons(text)","text":"
Uses chat compoletion model. A function that completes a template to check the maliciousness of some text. Prompt credit to Langchain Eval. Also uses chain of thought methodology and emits the reasons.
Usage:
feedback = Feedback(provider.maliciousness_with_cot_reasons).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not malicious) and 1.0 (malicious).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def maliciousness_with_cot_reasons(self, text: str) -> float:\n \"\"\"\n Uses chat compoletion model. A function that completes a\n template to check the maliciousness of some text. Prompt credit to Langchain Eval.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.maliciousness_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not malicious) and 1.0 (malicious).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_MALICIOUSNESS_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.misogyny","title":"
misogyny(text)","text":"
Uses chat completion model. A function that completes a template to check the misogyny of some text. Prompt credit to Langchain Eval.
Usage:
feedback = Feedback(provider.misogyny).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not misogynistic) and 1.0 (misogynistic).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def misogyny(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the misogyny of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.misogyny).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not misogynistic) and 1.0 (misogynistic).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_MISOGYNY_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.misogyny_with_cot_reasons","title":"
misogyny_with_cot_reasons(text)","text":"
Uses chat completion model. A function that completes a template to check the misogyny of some text. Prompt credit to Langchain Eval. Also uses chain of thought methodology and emits the reasons.
Usage:
feedback = Feedback(provider.misogyny_with_cot_reasons).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not misogynistic) and 1.0 (misogynistic).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def misogyny_with_cot_reasons(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the misogyny of some text. Prompt credit to Langchain Eval. Also\n uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.misogyny_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not misogynistic) and 1.0 (misogynistic).\n \"\"\"\n system_prompt = prompts.LANGCHAIN_MISOGYNY_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.model_agreement","title":"
model_agreement(prompt, response)","text":"
Uses chat completion model. A function that gives a chat completion model the same prompt and gets a response, encouraging truthfulness. A second template is given to the model with a prompt that the original response is correct, and measures whether previous chat completion response is similar.
Usage:
feedback = Feedback(provider.model_agreement).on_input_output() \n
The on_input_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
prompt str A text prompt to an agent.
required
response str The agent's response to the prompt.
required
Returns:
Name Type Description
float float A value between 0.0 (not in agreement) and 1.0 (in agreement).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def model_agreement(self, prompt: str, response: str) -> float:\n \"\"\"\n Uses chat completion model. A function that gives a chat completion model the same\n prompt and gets a response, encouraging truthfulness. A second template\n is given to the model with a prompt that the original response is\n correct, and measures whether previous chat completion response is similar.\n\n **Usage:**\n\n ```python\n feedback = Feedback(provider.model_agreement).on_input_output() \n ```\n\n The `on_input_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Parameters:\n prompt (str): A text prompt to an agent.\n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0.0 (not in agreement) and 1.0 (in agreement).\n \"\"\"\n warnings.warn(\n \"`model_agreement` has been deprecated. \"\n \"Use `GroundTruthAgreement(ground_truth)` instead.\",\n DeprecationWarning\n )\n chat_response = self._create_chat_completion(\n prompt=prompts.CORRECT_SYSTEM_PROMPT\n )\n agreement_txt = self._get_answer_agreement(\n prompt, response, chat_response\n )\n return re_0_10_rating(agreement_txt) / 10.0\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.qs_relevance","title":"
qs_relevance(question, statement)","text":"
Uses chat completion model. A function that completes a template to check the relevance of the statement to the question.
feedback = Feedback(provider.qs_relevance).on_input_output() \n
The
on_input_output() selector can be changed. See Feedback Function Guide
Usage on RAG Contexts:
feedback = Feedback(provider.qs_relevance).on_input().on(\n TruLlama.select_source_nodes().node.text # See note below\n).aggregate(np.mean) \n
The on(...) selector can be changed. See Feedback Function Guide : Selectors
Parameters:
Name Type Description Default
question str A question being asked.
required
statement str A statement to the question.
required
Returns:
Name Type Description
float float A value between 0.0 (not relevant) and 1.0 (relevant).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def qs_relevance(self, question: str, statement: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the relevance of the statement to the question.\n\n ```python\n feedback = Feedback(provider.qs_relevance).on_input_output() \n ```\n The `on_input_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Usage on RAG Contexts:\n\n ```python\n feedback = Feedback(provider.qs_relevance).on_input().on(\n TruLlama.select_source_nodes().node.text # See note below\n ).aggregate(np.mean) \n ```\n\n The `on(...)` selector can be changed. See [Feedback Function Guide :\n Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Args:\n question (str): A question being asked. \n statement (str): A statement to the question.\n\n Returns:\n float: A value between 0.0 (not relevant) and 1.0 (relevant).\n \"\"\"\n return re_0_10_rating(\n self.endpoint.run_me(\n lambda: self._create_chat_completion(\n prompt=str.format(\n prompts.QS_RELEVANCE,\n question=question,\n statement=statement\n )\n )\n )\n ) / 10\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.qs_relevance_with_cot_reasons","title":"
qs_relevance_with_cot_reasons(question, statement)","text":"
Uses chat completion model. A function that completes a template to check the relevance of the statement to the question. Also uses chain of thought methodology and emits the reasons.
Usage:
feedback = Feedback(provider.qs_relevance_with_cot_reasons).on_input_output() \n
The
on_input_output() selector can be changed. See Feedback Function Guide
Usage on RAG Contexts:
feedback = Feedback(provider.qs_relevance_with_cot_reasons).on_input().on(\n TruLlama.select_source_nodes().node.text # See note below\n).aggregate(np.mean) \n
The
on(...) selector can be changed. See Feedback Function Guide : Selectors
Parameters:
Name Type Description Default
question str A question being asked.
required
statement str A statement to the question.
required
Returns:
Name Type Description
float float A value between 0 and 1. 0 being \"not relevant\" and 1 being \"relevant\".
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def qs_relevance_with_cot_reasons(\n self, question: str, statement: str\n) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a\n template to check the relevance of the statement to the question.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```\n feedback = Feedback(provider.qs_relevance_with_cot_reasons).on_input_output() \n ```\n The `on_input_output()` selector can be changed. See [Feedback Function Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Usage on RAG Contexts:\n ```\n feedback = Feedback(provider.qs_relevance_with_cot_reasons).on_input().on(\n TruLlama.select_source_nodes().node.text # See note below\n ).aggregate(np.mean) \n\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n\n Args:\n question (str): A question being asked. \n statement (str): A statement to the question.\n\n Returns:\n float: A value between 0 and 1. 0 being \"not relevant\" and 1 being \"relevant\".\n \"\"\"\n system_prompt = str.format(\n prompts.QS_RELEVANCE, question=question, statement=statement\n )\n system_prompt = system_prompt.replace(\n \"RELEVANCE:\", prompts.COT_REASONS_TEMPLATE\n )\n return self.endpoint.run_me(\n lambda: self.\n _extract_score_and_reasons_from_response(system_prompt)\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.relevance","title":"
relevance(prompt, response)","text":"
Uses chat completion model. A function that completes a template to check the relevance of the response to a prompt.
Usage:
feedback = Feedback(provider.relevance).on_input_output()\n
The on_input_output() selector can be changed. See Feedback Function Guide
Usage on RAG Contexts:
feedback = Feedback(provider.relevance).on_input().on(\n TruLlama.select_source_nodes().node.text # See note below\n).aggregate(np.mean) \n
The on(...) selector can be changed. See Feedback Function Guide : Selectors
Parameters:
Name Type Description Default
prompt str A text prompt to an agent.
required
response str The agent's response to the prompt.
required
Returns:
Name Type Description
float float A value between 0 and 1. 0 being \"not relevant\" and 1 being
float \"relevant\".
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def relevance(self, prompt: str, response: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a\n template to check the relevance of the response to a prompt.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.relevance).on_input_output()\n ```\n\n The `on_input_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Usage on RAG Contexts:\n\n ```python\n feedback = Feedback(provider.relevance).on_input().on(\n TruLlama.select_source_nodes().node.text # See note below\n ).aggregate(np.mean) \n ```\n\n The `on(...)` selector can be changed. See [Feedback Function Guide :\n Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Parameters:\n prompt (str): A text prompt to an agent.\n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0 and 1. 0 being \"not relevant\" and 1 being\n \"relevant\".\n \"\"\"\n return re_0_10_rating(\n self.endpoint.run_me(\n lambda: self._create_chat_completion(\n prompt=str.format(\n prompts.PR_RELEVANCE, prompt=prompt, response=response\n )\n )\n )\n ) / 10.0\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.relevance_with_cot_reasons","title":"
relevance_with_cot_reasons(prompt, response)","text":"
Uses chat completion Model. A function that completes a template to check the relevance of the response to a prompt. Also uses chain of thought methodology and emits the reasons.
Usage:
feedback = Feedback(provider.relevance_with_cot_reasons).on_input_output()\n
The on_input_output() selector can be changed. See Feedback Function Guide
Usage on RAG Contexts:
feedback = Feedback(provider.relevance_with_cot_reasons).on_input().on(\n TruLlama.select_source_nodes().node.text # See note below\n).aggregate(np.mean) \n
The on(...) selector can be changed. See Feedback Function Guide : Selectors
Parameters:
Name Type Description Default
prompt str A text prompt to an agent.
required
response str The agent's response to the prompt.
required
Returns:
Name Type Description
float float A value between 0 and 1. 0 being \"not relevant\" and 1 being
float \"relevant\".
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def relevance_with_cot_reasons(self, prompt: str, response: str) -> float:\n \"\"\"\n Uses chat completion Model. A function that completes a template to\n check the relevance of the response to a prompt. Also uses chain of\n thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.relevance_with_cot_reasons).on_input_output()\n ```\n\n The `on_input_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Usage on RAG Contexts:\n ```python\n\n feedback = Feedback(provider.relevance_with_cot_reasons).on_input().on(\n TruLlama.select_source_nodes().node.text # See note below\n ).aggregate(np.mean) \n ```\n\n The `on(...)` selector can be changed. See [Feedback Function Guide :\n Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Args:\n prompt (str): A text prompt to an agent. \n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0 and 1. 0 being \"not relevant\" and 1 being\n \"relevant\".\n \"\"\"\n system_prompt = str.format(\n prompts.PR_RELEVANCE, prompt=prompt, response=response\n )\n system_prompt = system_prompt.replace(\n \"RELEVANCE:\", prompts.COT_REASONS_TEMPLATE\n )\n return self._extract_score_and_reasons_from_response(system_prompt)\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.sentiment","title":"
sentiment(text)","text":"
Uses chat completion model. A function that completes a template to check the sentiment of some text.
Usage:
feedback = Feedback(provider.sentiment).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str A prompt to an agent.
required
response str The agent's response to the prompt.
required
Returns:
Name Type Description
float float A value between 0 and 1. 0 being \"negative sentiment\" and 1
float being \"positive sentiment\".
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def sentiment(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check the sentiment of some text.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.sentiment).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Parameters:\n text (str): A prompt to an agent.\n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0 and 1. 0 being \"negative sentiment\" and 1\n being \"positive sentiment\".\n \"\"\"\n\n return re_0_10_rating(\n self.endpoint.run_me(\n lambda: self._create_chat_completion(\n prompt=prompts.SENTIMENT_SYSTEM_PROMPT + text\n )\n )\n ) / 10.0\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.sentiment_with_cot_reasons","title":"
sentiment_with_cot_reasons(text)","text":"
Uses chat completion model. A function that completes a template to check the sentiment of some text. Also uses chain of thought methodology and emits the reasons.
Usage:
feedback = Feedback(provider.sentiment_with_cot_reasons).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str Text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (negative sentiment) and 1.0 (positive sentiment).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def sentiment_with_cot_reasons(self, text: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a\n template to check the sentiment of some text.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n\n ```python\n feedback = Feedback(provider.sentiment_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (negative sentiment) and 1.0 (positive sentiment).\n \"\"\"\n\n system_prompt = prompts.SENTIMENT_SYSTEM_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.stereotypes","title":"
stereotypes(prompt, response)","text":"
Uses chat completion model. A function that completes a template to check adding assumed stereotypes in the response when not present in the prompt.
Usage:
feedback = Feedback(provider.stereotypes).on_input_output()\n
Parameters:
Name Type Description Default
prompt str A text prompt to an agent.
required
response str The agent's response to the prompt.
required
Returns:
Name Type Description
float float A value between 0.0 (no stereotypes assumed) and 1.0
float (stereotypes assumed).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def stereotypes(self, prompt: str, response: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check adding assumed stereotypes in the response when not present in the\n prompt.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.stereotypes).on_input_output()\n ```\n\n Args:\n prompt (str): A text prompt to an agent. \n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0.0 (no stereotypes assumed) and 1.0\n (stereotypes assumed).\n \"\"\"\n\n system_prompt = str.format(\n prompts.STEREOTYPES_PROMPT, prompt=prompt, response=response\n )\n\n return self._extract_score_and_reasons_from_response(system_prompt)\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.stereotypes_with_cot_reasons","title":"
stereotypes_with_cot_reasons(prompt, response)","text":"
Uses chat completion model. A function that completes a template to check adding assumed stereotypes in the response when not present in the prompt.
Usage:
feedback = Feedback(provider.stereotypes).on_input_output()\n
Parameters:
Name Type Description Default
prompt str A text prompt to an agent.
required
response str The agent's response to the prompt.
required
Returns:
Name Type Description
float float A value between 0.0 (no stereotypes assumed) and 1.0
float (stereotypes assumed).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def stereotypes_with_cot_reasons(self, prompt: str, response: str) -> float:\n \"\"\"\n Uses chat completion model. A function that completes a template to\n check adding assumed stereotypes in the response when not present in the\n prompt.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.stereotypes).on_input_output()\n ```\n\n Args:\n prompt (str): A text prompt to an agent. \n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0.0 (no stereotypes assumed) and 1.0\n (stereotypes assumed).\n \"\"\"\n system_prompt = str.format(\n prompts.STEREOTYPES_PROMPT, prompt=prompt, response=response\n )\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n\n return self._extract_score_and_reasons_from_response(system_prompt)\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.summary_with_cot_reasons","title":"
summary_with_cot_reasons(source, summary)","text":"
Uses chat completion model. A function that tries to distill main points and compares a summary against those main points. This feedback function only has a chain of thought implementation as it is extremely important in function assessment.
Usage:
feedback = Feedback(provider.summary_with_cot_reasons).on_input_output()\n
Parameters:
Name Type Description Default
source str Text corresponding to source material.
required
summary str Text corresponding to a summary.
required
Returns:
Name Type Description
float float A value between 0.0 (main points missed) and 1.0 (no main
float points missed).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def summary_with_cot_reasons(self, source: str, summary: str) -> float:\n \"\"\"\n Uses chat completion model. A function that tries to distill main points\n and compares a summary against those main points. This feedback function\n only has a chain of thought implementation as it is extremely important\n in function assessment.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.summary_with_cot_reasons).on_input_output()\n ```\n\n Args:\n source (str): Text corresponding to source material. \n summary (str): Text corresponding to a summary.\n\n Returns:\n float: A value between 0.0 (main points missed) and 1.0 (no main\n points missed).\n \"\"\"\n\n system_prompt = str.format(\n prompts.SUMMARIZATION_PROMPT, source=source, summary=summary\n )\n\n return self._extract_score_and_reasons_from_response(system_prompt)\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.groundedness.Groundedness","title":"
Groundedness","text":"
Bases: SerialModel, WithClassInfo
Measures Groundedness.
Source code in
trulens_eval/trulens_eval/feedback/groundedness.py class Groundedness(SerialModel, WithClassInfo):\n \"\"\"Measures Groundedness.\n \"\"\"\n groundedness_provider: Provider\n\n def __init__(self, groundedness_provider: Provider = None):\n \"\"\"Instantiates the groundedness providers. Currently the groundedness functions work well with a summarizer.\n This class will use an LLM to find the relevant strings in a text. The groundedness_provider can \n either be an LLM provider (such as OpenAI) or NLI with huggingface.\n\n Usage 1:\n ```\n from trulens_eval.feedback import Groundedness\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n groundedness_imp = Groundedness(groundedness_provider=openai_provider)\n ```\n\n Usage 2:\n ```\n from trulens_eval.feedback import Groundedness\n from trulens_eval.feedback.provider.hugs import Huggingface\n huggingface_provider = Huggingface()\n groundedness_imp = Groundedness(groundedness_provider=huggingface_provider)\n ```\n\n Args:\n groundedness_provider (Provider, optional): groundedness provider options: OpenAI LLM or HuggingFace NLI. Defaults to OpenAI().\n summarize_provider (Provider, optional): Internal Usage for DB serialization.\n \"\"\"\n\n if groundedness_provider is None:\n groundedness_provider = OpenAI()\n super().__init__(\n groundedness_provider=groundedness_provider,\n obj=self # for WithClassInfo\n )\n\n def groundedness_measure(self, source: str, statement: str) -> float:\n \"\"\"A measure to track if the source material supports each sentence in the statement. \n This groundedness measure is faster; but less accurate than `groundedness_measure_with_summarize_step` \n\n Usage on RAG Contexts:\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import Groundedness\n from trulens_eval.feedback.provider.openai import OpenAI\n grounded = feedback.Groundedness(groundedness_provider=OpenAI())\n\n\n f_groundedness = feedback.Feedback(grounded.groundedness_measure).on(\n Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content # See note below\n ).on_output().aggregate(grounded.grounded_statements_aggregator)\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n\n Args:\n source (str): The source that should support the statement\n statement (str): The statement to check groundedness\n\n Returns:\n float: A measure between 0 and 1, where 1 means each sentence is grounded in the source.\n \"\"\"\n logger.warning(\n \"Feedback function `groundedness_measure` was renamed to `groundedness_measure_with_cot_reasons`. The new functionality of `groundedness_measure` function will no longer emit reasons as a lower cost option. It may have reduced accuracy due to not using Chain of Thought reasoning in the scoring.\"\n )\n\n groundedness_scores = {}\n if isinstance(self.groundedness_provider,\n (AzureOpenAI, OpenAI, LiteLLM, Bedrock)):\n groundedness_scores[f\"full_doc_score\"] = re_0_10_rating(\n self.groundedness_provider.\n _groundedness_doc_in_out(source, statement)\n ) / 10\n reason = \"Reasons not supplied for non chain of thought function\"\n elif isinstance(self.groundedness_provider, Huggingface):\n reason = \"\"\n for i, hypothesis in enumerate(\n tqdm(statement.split(\".\"),\n desc=\"Groundendess per statement in source\")):\n plausible_junk_char_min = 4 # very likely \"sentences\" under 4 characters are punctuation, spaces, etc\n if len(hypothesis) > plausible_junk_char_min:\n score = self.groundedness_provider._doc_groundedness(\n premise=source, hypothesis=hypothesis\n )\n reason = reason + str.format(\n prompts.GROUNDEDNESS_REASON_TEMPLATE,\n statement_sentence=hypothesis,\n supporting_evidence=\"[Doc NLI Used full source]\",\n score=score * 10,\n )\n groundedness_scores[f\"statement_{i}\"] = score\n\n return groundedness_scores, {\"reason\": reason}\n\n def groundedness_measure_with_cot_reasons(\n self, source: str, statement: str\n ) -> float:\n \"\"\"A measure to track if the source material supports each sentence in the statement. \n This groundedness measure is faster; but less accurate than `groundedness_measure_with_summarize_step`.\n Also uses chain of thought methodology and emits the reasons.\n\n Usage on RAG Contexts:\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import Groundedness\n from trulens_eval.feedback.provider.openai import OpenAI\n grounded = feedback.Groundedness(groundedness_provider=OpenAI())\n\n\n f_groundedness = feedback.Feedback(grounded.groundedness_measure_with_cot_reasons).on(\n Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content # See note below\n ).on_output().aggregate(grounded.grounded_statements_aggregator)\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n\n Args:\n source (str): The source that should support the statement\n statement (str): The statement to check groundedness\n\n Returns:\n float: A measure between 0 and 1, where 1 means each sentence is grounded in the source.\n \"\"\"\n groundedness_scores = {}\n if isinstance(self.groundedness_provider,\n (AzureOpenAI, OpenAI, LiteLLM, Bedrock)):\n plausible_junk_char_min = 4 # very likely \"sentences\" under 4 characters are punctuation, spaces, etc\n if len(statement) > plausible_junk_char_min:\n reason = self.groundedness_provider._groundedness_doc_in_out(\n source, statement\n )\n i = 0\n for line in reason.split('\\n'):\n if \"Score\" in line:\n groundedness_scores[f\"statement_{i}\"\n ] = re_0_10_rating(line) / 10\n i += 1\n return groundedness_scores, {\"reason\": reason}\n elif isinstance(self.groundedness_provider, Huggingface):\n raise Exception(\n \"Chain of Thought reasoning is only applicable to OpenAI groundedness providers. Instantiate `Groundedness(groundedness_provider=OpenAI())` or use `groundedness_measure` feedback function.\"\n )\n\n def groundedness_measure_with_summarize_step(\n self, source: str, statement: str\n ) -> float:\n \"\"\"A measure to track if the source material supports each sentence in the statement. \n This groundedness measure is more accurate; but slower using a two step process.\n - First find supporting evidence with an LLM\n - Then for each statement sentence, check groundendness\n\n Usage on RAG Contexts:\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import Groundedness\n from trulens_eval.feedback.provider.openai import OpenAI\n grounded = feedback.Groundedness(groundedness_provider=OpenAI())\n\n\n f_groundedness = feedback.Feedback(grounded.groundedness_measure_with_summarize_step).on(\n Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content # See note below\n ).on_output().aggregate(grounded.grounded_statements_aggregator)\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n\n Args:\n source (str): The source that should support the statement\n statement (str): The statement to check groundedness\n\n Returns:\n float: A measure between 0 and 1, where 1 means each sentence is grounded in the source.\n \"\"\"\n groundedness_scores = {}\n reason = \"\"\n for i, hypothesis in enumerate(\n tqdm(statement.split(\".\"),\n desc=\"Groundendess per statement in source\")):\n plausible_junk_char_min = 4 # very likely \"sentences\" under 4 characters are punctuation, spaces, etc\n if len(hypothesis) > plausible_junk_char_min:\n supporting_premise = self.groundedness_provider._find_relevant_string(\n source, hypothesis\n )\n score = self.groundedness_provider._summarized_groundedness(\n premise=supporting_premise, hypothesis=hypothesis\n )\n reason = reason + str.format(\n prompts.GROUNDEDNESS_REASON_TEMPLATE,\n statement_sentence=hypothesis,\n supporting_evidence=supporting_premise,\n score=score * 10,\n )\n groundedness_scores[f\"statement_{i}\"] = score\n return groundedness_scores, {\"reason\": reason}\n\n def grounded_statements_aggregator(\n self, source_statements_multi_output: List[Dict]\n ) -> float:\n \"\"\"Aggregates multi-input, mulit-output information from the groundedness_measure methods.\n\n\n Args:\n source_statements_multi_output (List[Dict]): A list of scores. Each list index is a context. The Dict is a per statement score.\n\n Returns:\n float: for each statement, gets the max groundedness, then averages over that.\n \"\"\"\n all_results = []\n\n statements_to_scores = {}\n\n # Ensure source_statements_multi_output is a list\n if not isinstance(source_statements_multi_output, list):\n source_statements_multi_output = [source_statements_multi_output]\n\n for multi_output in source_statements_multi_output:\n for k in multi_output:\n if k not in statements_to_scores:\n statements_to_scores[k] = []\n statements_to_scores[k].append(multi_output[k])\n\n for k in statements_to_scores:\n all_results.append(np.max(statements_to_scores[k]))\n\n return np.mean(all_results)\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.groundedness.Groundedness.__init__","title":"
__init__(groundedness_provider=None)","text":"
Instantiates the groundedness providers. Currently the groundedness functions work well with a summarizer. This class will use an LLM to find the relevant strings in a text. The groundedness_provider can either be an LLM provider (such as OpenAI) or NLI with huggingface.
Usage 1:
from trulens_eval.feedback import Groundedness\nfrom trulens_eval.feedback.provider.openai import OpenAI\nopenai_provider = OpenAI()\ngroundedness_imp = Groundedness(groundedness_provider=openai_provider)\n
Usage 2:
from trulens_eval.feedback import Groundedness\nfrom trulens_eval.feedback.provider.hugs import Huggingface\nhuggingface_provider = Huggingface()\ngroundedness_imp = Groundedness(groundedness_provider=huggingface_provider)\n
Parameters:
Name Type Description Default
groundedness_provider Provider groundedness provider options: OpenAI LLM or HuggingFace NLI. Defaults to OpenAI().
None summarize_provider Provider Internal Usage for DB serialization.
required Source code in
trulens_eval/trulens_eval/feedback/groundedness.py def __init__(self, groundedness_provider: Provider = None):\n \"\"\"Instantiates the groundedness providers. Currently the groundedness functions work well with a summarizer.\n This class will use an LLM to find the relevant strings in a text. The groundedness_provider can \n either be an LLM provider (such as OpenAI) or NLI with huggingface.\n\n Usage 1:\n ```\n from trulens_eval.feedback import Groundedness\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n groundedness_imp = Groundedness(groundedness_provider=openai_provider)\n ```\n\n Usage 2:\n ```\n from trulens_eval.feedback import Groundedness\n from trulens_eval.feedback.provider.hugs import Huggingface\n huggingface_provider = Huggingface()\n groundedness_imp = Groundedness(groundedness_provider=huggingface_provider)\n ```\n\n Args:\n groundedness_provider (Provider, optional): groundedness provider options: OpenAI LLM or HuggingFace NLI. Defaults to OpenAI().\n summarize_provider (Provider, optional): Internal Usage for DB serialization.\n \"\"\"\n\n if groundedness_provider is None:\n groundedness_provider = OpenAI()\n super().__init__(\n groundedness_provider=groundedness_provider,\n obj=self # for WithClassInfo\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.groundedness.Groundedness.grounded_statements_aggregator","title":"
grounded_statements_aggregator(source_statements_multi_output)","text":"
Aggregates multi-input, mulit-output information from the groundedness_measure methods.
Parameters:
Name Type Description Default
source_statements_multi_output List[Dict] A list of scores. Each list index is a context. The Dict is a per statement score.
required
Returns:
Name Type Description
float float for each statement, gets the max groundedness, then averages over that.
Source code in
trulens_eval/trulens_eval/feedback/groundedness.py def grounded_statements_aggregator(\n self, source_statements_multi_output: List[Dict]\n) -> float:\n \"\"\"Aggregates multi-input, mulit-output information from the groundedness_measure methods.\n\n\n Args:\n source_statements_multi_output (List[Dict]): A list of scores. Each list index is a context. The Dict is a per statement score.\n\n Returns:\n float: for each statement, gets the max groundedness, then averages over that.\n \"\"\"\n all_results = []\n\n statements_to_scores = {}\n\n # Ensure source_statements_multi_output is a list\n if not isinstance(source_statements_multi_output, list):\n source_statements_multi_output = [source_statements_multi_output]\n\n for multi_output in source_statements_multi_output:\n for k in multi_output:\n if k not in statements_to_scores:\n statements_to_scores[k] = []\n statements_to_scores[k].append(multi_output[k])\n\n for k in statements_to_scores:\n all_results.append(np.max(statements_to_scores[k]))\n\n return np.mean(all_results)\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.groundedness.Groundedness.groundedness_measure","title":"
groundedness_measure(source, statement)","text":"
A measure to track if the source material supports each sentence in the statement. This groundedness measure is faster; but less accurate than groundedness_measure_with_summarize_step
Usage on RAG Contexts:
from trulens_eval import Feedback\nfrom trulens_eval.feedback import Groundedness\nfrom trulens_eval.feedback.provider.openai import OpenAI\ngrounded = feedback.Groundedness(groundedness_provider=OpenAI())\n\n\nf_groundedness = feedback.Feedback(grounded.groundedness_measure).on(\n Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content # See note below\n).on_output().aggregate(grounded.grounded_statements_aggregator)\n
The
on(...) selector can be changed. See Feedback Function Guide : Selectors
Parameters:
Name Type Description Default
source str The source that should support the statement
required
statement str The statement to check groundedness
required
Returns:
Name Type Description
float float A measure between 0 and 1, where 1 means each sentence is grounded in the source.
Source code in
trulens_eval/trulens_eval/feedback/groundedness.py def groundedness_measure(self, source: str, statement: str) -> float:\n \"\"\"A measure to track if the source material supports each sentence in the statement. \n This groundedness measure is faster; but less accurate than `groundedness_measure_with_summarize_step` \n\n Usage on RAG Contexts:\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import Groundedness\n from trulens_eval.feedback.provider.openai import OpenAI\n grounded = feedback.Groundedness(groundedness_provider=OpenAI())\n\n\n f_groundedness = feedback.Feedback(grounded.groundedness_measure).on(\n Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content # See note below\n ).on_output().aggregate(grounded.grounded_statements_aggregator)\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n\n Args:\n source (str): The source that should support the statement\n statement (str): The statement to check groundedness\n\n Returns:\n float: A measure between 0 and 1, where 1 means each sentence is grounded in the source.\n \"\"\"\n logger.warning(\n \"Feedback function `groundedness_measure` was renamed to `groundedness_measure_with_cot_reasons`. The new functionality of `groundedness_measure` function will no longer emit reasons as a lower cost option. It may have reduced accuracy due to not using Chain of Thought reasoning in the scoring.\"\n )\n\n groundedness_scores = {}\n if isinstance(self.groundedness_provider,\n (AzureOpenAI, OpenAI, LiteLLM, Bedrock)):\n groundedness_scores[f\"full_doc_score\"] = re_0_10_rating(\n self.groundedness_provider.\n _groundedness_doc_in_out(source, statement)\n ) / 10\n reason = \"Reasons not supplied for non chain of thought function\"\n elif isinstance(self.groundedness_provider, Huggingface):\n reason = \"\"\n for i, hypothesis in enumerate(\n tqdm(statement.split(\".\"),\n desc=\"Groundendess per statement in source\")):\n plausible_junk_char_min = 4 # very likely \"sentences\" under 4 characters are punctuation, spaces, etc\n if len(hypothesis) > plausible_junk_char_min:\n score = self.groundedness_provider._doc_groundedness(\n premise=source, hypothesis=hypothesis\n )\n reason = reason + str.format(\n prompts.GROUNDEDNESS_REASON_TEMPLATE,\n statement_sentence=hypothesis,\n supporting_evidence=\"[Doc NLI Used full source]\",\n score=score * 10,\n )\n groundedness_scores[f\"statement_{i}\"] = score\n\n return groundedness_scores, {\"reason\": reason}\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.groundedness.Groundedness.groundedness_measure_with_cot_reasons","title":"
groundedness_measure_with_cot_reasons(source, statement)","text":"
A measure to track if the source material supports each sentence in the statement. This groundedness measure is faster; but less accurate than groundedness_measure_with_summarize_step. Also uses chain of thought methodology and emits the reasons.
Usage on RAG Contexts:
from trulens_eval import Feedback\nfrom trulens_eval.feedback import Groundedness\nfrom trulens_eval.feedback.provider.openai import OpenAI\ngrounded = feedback.Groundedness(groundedness_provider=OpenAI())\n\n\nf_groundedness = feedback.Feedback(grounded.groundedness_measure_with_cot_reasons).on(\n Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content # See note below\n).on_output().aggregate(grounded.grounded_statements_aggregator)\n
The
on(...) selector can be changed. See Feedback Function Guide : Selectors
Parameters:
Name Type Description Default
source str The source that should support the statement
required
statement str The statement to check groundedness
required
Returns:
Name Type Description
float float A measure between 0 and 1, where 1 means each sentence is grounded in the source.
Source code in
trulens_eval/trulens_eval/feedback/groundedness.py def groundedness_measure_with_cot_reasons(\n self, source: str, statement: str\n) -> float:\n \"\"\"A measure to track if the source material supports each sentence in the statement. \n This groundedness measure is faster; but less accurate than `groundedness_measure_with_summarize_step`.\n Also uses chain of thought methodology and emits the reasons.\n\n Usage on RAG Contexts:\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import Groundedness\n from trulens_eval.feedback.provider.openai import OpenAI\n grounded = feedback.Groundedness(groundedness_provider=OpenAI())\n\n\n f_groundedness = feedback.Feedback(grounded.groundedness_measure_with_cot_reasons).on(\n Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content # See note below\n ).on_output().aggregate(grounded.grounded_statements_aggregator)\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n\n Args:\n source (str): The source that should support the statement\n statement (str): The statement to check groundedness\n\n Returns:\n float: A measure between 0 and 1, where 1 means each sentence is grounded in the source.\n \"\"\"\n groundedness_scores = {}\n if isinstance(self.groundedness_provider,\n (AzureOpenAI, OpenAI, LiteLLM, Bedrock)):\n plausible_junk_char_min = 4 # very likely \"sentences\" under 4 characters are punctuation, spaces, etc\n if len(statement) > plausible_junk_char_min:\n reason = self.groundedness_provider._groundedness_doc_in_out(\n source, statement\n )\n i = 0\n for line in reason.split('\\n'):\n if \"Score\" in line:\n groundedness_scores[f\"statement_{i}\"\n ] = re_0_10_rating(line) / 10\n i += 1\n return groundedness_scores, {\"reason\": reason}\n elif isinstance(self.groundedness_provider, Huggingface):\n raise Exception(\n \"Chain of Thought reasoning is only applicable to OpenAI groundedness providers. Instantiate `Groundedness(groundedness_provider=OpenAI())` or use `groundedness_measure` feedback function.\"\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.groundedness.Groundedness.groundedness_measure_with_summarize_step","title":"
groundedness_measure_with_summarize_step(source, statement)","text":"
A measure to track if the source material supports each sentence in the statement. This groundedness measure is more accurate; but slower using a two step process. - First find supporting evidence with an LLM - Then for each statement sentence, check groundendness
Usage on RAG Contexts:
from trulens_eval import Feedback\nfrom trulens_eval.feedback import Groundedness\nfrom trulens_eval.feedback.provider.openai import OpenAI\ngrounded = feedback.Groundedness(groundedness_provider=OpenAI())\n\n\nf_groundedness = feedback.Feedback(grounded.groundedness_measure_with_summarize_step).on(\n Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content # See note below\n).on_output().aggregate(grounded.grounded_statements_aggregator)\n
The
on(...) selector can be changed. See Feedback Function Guide : Selectors
Parameters:
Name Type Description Default
source str The source that should support the statement
required
statement str The statement to check groundedness
required
Returns:
Name Type Description
float float A measure between 0 and 1, where 1 means each sentence is grounded in the source.
Source code in
trulens_eval/trulens_eval/feedback/groundedness.py def groundedness_measure_with_summarize_step(\n self, source: str, statement: str\n) -> float:\n \"\"\"A measure to track if the source material supports each sentence in the statement. \n This groundedness measure is more accurate; but slower using a two step process.\n - First find supporting evidence with an LLM\n - Then for each statement sentence, check groundendness\n\n Usage on RAG Contexts:\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import Groundedness\n from trulens_eval.feedback.provider.openai import OpenAI\n grounded = feedback.Groundedness(groundedness_provider=OpenAI())\n\n\n f_groundedness = feedback.Feedback(grounded.groundedness_measure_with_summarize_step).on(\n Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content # See note below\n ).on_output().aggregate(grounded.grounded_statements_aggregator)\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n\n Args:\n source (str): The source that should support the statement\n statement (str): The statement to check groundedness\n\n Returns:\n float: A measure between 0 and 1, where 1 means each sentence is grounded in the source.\n \"\"\"\n groundedness_scores = {}\n reason = \"\"\n for i, hypothesis in enumerate(\n tqdm(statement.split(\".\"),\n desc=\"Groundendess per statement in source\")):\n plausible_junk_char_min = 4 # very likely \"sentences\" under 4 characters are punctuation, spaces, etc\n if len(hypothesis) > plausible_junk_char_min:\n supporting_premise = self.groundedness_provider._find_relevant_string(\n source, hypothesis\n )\n score = self.groundedness_provider._summarized_groundedness(\n premise=supporting_premise, hypothesis=hypothesis\n )\n reason = reason + str.format(\n prompts.GROUNDEDNESS_REASON_TEMPLATE,\n statement_sentence=hypothesis,\n supporting_evidence=supporting_premise,\n score=score * 10,\n )\n groundedness_scores[f\"statement_{i}\"] = score\n return groundedness_scores, {\"reason\": reason}\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.groundtruth.GroundTruthAgreement","title":"
GroundTruthAgreement","text":"
Bases: SerialModel, WithClassInfo
Measures Agreement against a Ground Truth.
Source code in
trulens_eval/trulens_eval/feedback/groundtruth.py class GroundTruthAgreement(SerialModel, WithClassInfo):\n \"\"\"Measures Agreement against a Ground Truth.\n \"\"\"\n ground_truth: Union[List[str], FunctionOrMethod]\n provider: Provider\n # Note: the bert scorer object isn't serializable\n # It's a class member because creating it is expensive\n bert_scorer: object\n\n ground_truth_imp: Optional[Callable] = pydantic.Field(exclude=True)\n\n class Config:\n arbitrary_types_allowed = True\n\n def __init__(\n self,\n ground_truth: Union[List, Callable, FunctionOrMethod],\n provider: Provider = None,\n bert_scorer: Optional[\"BERTScorer\"] = None\n ):\n \"\"\"Measures Agreement against a Ground Truth. \n\n Usage 1:\n ```\n from trulens_eval.feedback import GroundTruthAgreement\n golden_set = [\n {\"query\": \"who invented the lightbulb?\", \"response\": \"Thomas Edison\"},\n {\"query\": \"\u00bfquien invento la bombilla?\", \"response\": \"Thomas Edison\"}\n ]\n ground_truth_collection = GroundTruthAgreement(golden_set)\n ```\n\n Usage 2:\n ```\n from trulens_eval.feedback import GroundTruthAgreement\n ground_truth_imp = llm_app\n response = llm_app(prompt)\n ground_truth_collection = GroundTruthAgreement(ground_truth_imp)\n ```\n\n Args:\n ground_truth (Union[Callable, FunctionOrMethod]): A list of query/response pairs or a function or callable that returns a ground truth string given a prompt string.\n bert_scorer (Optional["BERTScorer"], optional): Internal Usage for DB serialization.\n provider (Provider, optional): Internal Usage for DB serialization.\n\n \"\"\"\n provider = OpenAI()\n if isinstance(ground_truth, List):\n ground_truth_imp = None\n elif isinstance(ground_truth, FunctionOrMethod):\n ground_truth_imp = ground_truth.load()\n elif isinstance(ground_truth, Callable):\n ground_truth_imp = ground_truth\n ground_truth = FunctionOrMethod.of_callable(ground_truth)\n elif isinstance(ground_truth, Dict):\n # Serialized FunctionOrMethod?\n ground_truth = FunctionOrMethod.pick(**ground_truth)\n ground_truth_imp = ground_truth.load()\n else:\n raise RuntimeError(\n f\"Unhandled ground_truth type: {type(ground_truth)}.\"\n )\n\n super().__init__(\n ground_truth=ground_truth,\n ground_truth_imp=ground_truth_imp,\n provider=provider,\n bert_scorer=bert_scorer,\n obj=self # for WithClassInfo\n )\n\n def _find_response(self, prompt: str) -> Optional[str]:\n if self.ground_truth_imp is not None:\n return self.ground_truth_imp(prompt)\n\n responses = [\n qr[\"response\"] for qr in self.ground_truth if qr[\"query\"] == prompt\n ]\n if responses:\n return responses[0]\n else:\n return None\n\n def _find_score(self, prompt: str, response: str) -> Optional[float]:\n if self.ground_truth_imp is not None:\n return self.ground_truth_imp(prompt)\n\n responses = [\n qr[\"expected_score\"]\n for qr in self.ground_truth\n if qr[\"query\"] == prompt and qr[\"response\"] == response\n ]\n if responses:\n return responses[0]\n else:\n return None\n\n # TODEP\n def agreement_measure(\n self, prompt: str, response: str\n ) -> Union[float, Tuple[float, Dict[str, str]]]:\n \"\"\"\n Uses OpenAI's Chat GPT Model. A function that that measures\n similarity to ground truth. A second template is given to Chat GPT\n with a prompt that the original response is correct, and measures\n whether previous Chat GPT's response is similar.\n\n **Usage:**\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import GroundTruthAgreement\n golden_set = [\n {\"query\": \"who invented the lightbulb?\", \"response\": \"Thomas Edison\"},\n {\"query\": \"\u00bfquien invento la bombilla?\", \"response\": \"Thomas Edison\"}\n ]\n ground_truth_collection = GroundTruthAgreement(golden_set)\n\n feedback = Feedback(ground_truth_collection.agreement_measure).on_input_output() \n ```\n The `on_input_output()` selector can be changed. See [Feedback Function Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n prompt (str): A text prompt to an agent. \n response (str): The agent's response to the prompt.\n\n Returns:\n - float: A value between 0 and 1. 0 being \"not in agreement\" and 1\n being \"in agreement\".\n - dict: with key 'ground_truth_response'\n \"\"\"\n ground_truth_response = self._find_response(prompt)\n if ground_truth_response:\n agreement_txt = self.provider._get_answer_agreement(\n prompt, response, ground_truth_response\n )\n ret = re_0_10_rating(agreement_txt) / 10, dict(\n ground_truth_response=ground_truth_response\n )\n else:\n ret = np.nan\n\n return ret\n\n def mae(self, prompt: str, response: str, score: float) -> float:\n \"\"\"\n Method to look up the numeric expected score from a golden set and take the differnce.\n\n Primarily used for evaluation of model generated feedback against human feedback\n\n **Usage**\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import GroundTruthAgreement\n\n golden_set =\n {\"query\": \"How many stomachs does a cow have?\", \"response\": \"Cows' diet relies primarily on grazing.\", \"expected_score\": 0.4},\n {\"query\": \"Name some top dental floss brands\", \"response\": \"I don't know\", \"expected_score\": 0.8}\n ]\n ground_truth_collection = GroundTruthAgreement(golden_set)\n\n f_groundtruth = Feedback(ground_truth.mae).on(Select.Record.calls[0].args.args[0]).on(Select.Record.calls[0].args.args[1]).on_output()\n ```\n\n \"\"\"\n\n expected_score = self._find_score(prompt, response)\n if expected_score:\n ret = abs(float(score) - expected_score)\n expected_score = \"{:.2f}\".format(expected_score\n ).rstrip('0').rstrip('.')\n else:\n ret = np.nan\n return ret, {\"expected score\": expected_score}\n\n def bert_score(self, prompt: str,\n response: str) -> Union[float, Tuple[float, Dict[str, str]]]:\n \"\"\"\n Uses BERT Score. A function that that measures\n similarity to ground truth using bert embeddings. \n\n **Usage:**\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import GroundTruthAgreement\n golden_set = [\n {\"query\": \"who invented the lightbulb?\", \"response\": \"Thomas Edison\"},\n {\"query\": \"\u00bfquien invento la bombilla?\", \"response\": \"Thomas Edison\"}\n ]\n ground_truth_collection = GroundTruthAgreement(golden_set)\n\n feedback = Feedback(ground_truth_collection.bert_score).on_input_output() \n ```\n The `on_input_output()` selector can be changed. See [Feedback Function Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n\n Args:\n prompt (str): A text prompt to an agent.\n response (str): The agent's response to the prompt.\n\n Returns:\n - float: A value between 0 and 1. 0 being \"not in agreement\" and 1\n being \"in agreement\".\n - dict: with key 'ground_truth_response'\n \"\"\"\n if self.bert_scorer is None:\n self.bert_scorer = BERTScorer(lang=\"en\", rescale_with_baseline=True)\n ground_truth_response = self._find_response(prompt)\n if ground_truth_response:\n bert_score = self.bert_scorer.score(\n [response], [ground_truth_response]\n )\n ret = bert_score[0].item(), dict(\n ground_truth_response=ground_truth_response\n )\n else:\n ret = np.nan\n\n return ret\n\n # TODEP\n def bleu(self, prompt: str,\n response: str) -> Union[float, Tuple[float, Dict[str, str]]]:\n \"\"\"\n Uses BLEU Score. A function that that measures\n similarity to ground truth using token overlap. \n\n **Usage:**\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import GroundTruthAgreement\n golden_set = [\n {\"query\": \"who invented the lightbulb?\", \"response\": \"Thomas Edison\"},\n {\"query\": \"\u00bfquien invento la bombilla?\", \"response\": \"Thomas Edison\"}\n ]\n ground_truth_collection = GroundTruthAgreement(golden_set)\n\n feedback = Feedback(ground_truth_collection.bleu).on_input_output() \n ```\n The `on_input_output()` selector can be changed. See [Feedback Function Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n prompt (str): A text prompt to an agent. \n response (str): The agent's response to the prompt.\n\n Returns:\n - float: A value between 0 and 1. 0 being \"not in agreement\" and 1\n being \"in agreement\".\n - dict: with key 'ground_truth_response'\n \"\"\"\n bleu = evaluate.load('bleu')\n ground_truth_response = self._find_response(prompt)\n if ground_truth_response:\n bleu_score = bleu.compute(\n predictions=[response], references=[ground_truth_response]\n )\n ret = bleu_score['bleu'], dict(\n ground_truth_response=ground_truth_response\n )\n else:\n ret = np.nan\n\n return ret\n\n # TODEP\n def rouge(self, prompt: str,\n response: str) -> Union[float, Tuple[float, Dict[str, str]]]:\n \"\"\"\n Uses BLEU Score. A function that that measures\n similarity to ground truth using token overlap. \n\n Args:\n prompt (str): A text prompt to an agent. \n response (str): The agent's response to the prompt.\n\n Returns:\n - float: A value between 0 and 1. 0 being \"not in agreement\" and 1\n being \"in agreement\".\n - dict: with key 'ground_truth_response'\n \"\"\"\n rouge = evaluate.load('rouge')\n ground_truth_response = self._find_response(prompt)\n if ground_truth_response:\n rouge_score = rouge.compute(\n predictions=[response], references=[ground_truth_response]\n )\n ret = rouge_score['rouge1'], dict(\n ground_truth_response=ground_truth_response\n )\n else:\n ret = np.nan\n\n return ret\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.groundtruth.GroundTruthAgreement.__init__","title":"
__init__(ground_truth, provider=None, bert_scorer=None)","text":"
Measures Agreement against a Ground Truth.
Usage 1:
from trulens_eval.feedback import GroundTruthAgreement\ngolden_set = [\n {\"query\": \"who invented the lightbulb?\", \"response\": \"Thomas Edison\"},\n {\"query\": \"\u00bfquien invento la bombilla?\", \"response\": \"Thomas Edison\"}\n]\nground_truth_collection = GroundTruthAgreement(golden_set)\n
Usage 2:
from trulens_eval.feedback import GroundTruthAgreement\nground_truth_imp = llm_app\nresponse = llm_app(prompt)\nground_truth_collection = GroundTruthAgreement(ground_truth_imp)\n
Parameters:
Name Type Description Default
ground_truth Union[Callable, FunctionOrMethod] A list of query/response pairs or a function or callable that returns a ground truth string given a prompt string.
required
bert_scorer Optional["BERTScorer"] Internal Usage for DB serialization.
None provider Provider Internal Usage for DB serialization.
None Source code in
trulens_eval/trulens_eval/feedback/groundtruth.py def __init__(\n self,\n ground_truth: Union[List, Callable, FunctionOrMethod],\n provider: Provider = None,\n bert_scorer: Optional[\"BERTScorer\"] = None\n):\n \"\"\"Measures Agreement against a Ground Truth. \n\n Usage 1:\n ```\n from trulens_eval.feedback import GroundTruthAgreement\n golden_set = [\n {\"query\": \"who invented the lightbulb?\", \"response\": \"Thomas Edison\"},\n {\"query\": \"\u00bfquien invento la bombilla?\", \"response\": \"Thomas Edison\"}\n ]\n ground_truth_collection = GroundTruthAgreement(golden_set)\n ```\n\n Usage 2:\n ```\n from trulens_eval.feedback import GroundTruthAgreement\n ground_truth_imp = llm_app\n response = llm_app(prompt)\n ground_truth_collection = GroundTruthAgreement(ground_truth_imp)\n ```\n\n Args:\n ground_truth (Union[Callable, FunctionOrMethod]): A list of query/response pairs or a function or callable that returns a ground truth string given a prompt string.\n bert_scorer (Optional["BERTScorer"], optional): Internal Usage for DB serialization.\n provider (Provider, optional): Internal Usage for DB serialization.\n\n \"\"\"\n provider = OpenAI()\n if isinstance(ground_truth, List):\n ground_truth_imp = None\n elif isinstance(ground_truth, FunctionOrMethod):\n ground_truth_imp = ground_truth.load()\n elif isinstance(ground_truth, Callable):\n ground_truth_imp = ground_truth\n ground_truth = FunctionOrMethod.of_callable(ground_truth)\n elif isinstance(ground_truth, Dict):\n # Serialized FunctionOrMethod?\n ground_truth = FunctionOrMethod.pick(**ground_truth)\n ground_truth_imp = ground_truth.load()\n else:\n raise RuntimeError(\n f\"Unhandled ground_truth type: {type(ground_truth)}.\"\n )\n\n super().__init__(\n ground_truth=ground_truth,\n ground_truth_imp=ground_truth_imp,\n provider=provider,\n bert_scorer=bert_scorer,\n obj=self # for WithClassInfo\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.groundtruth.GroundTruthAgreement.agreement_measure","title":"
agreement_measure(prompt, response)","text":"
Uses OpenAI's Chat GPT Model. A function that that measures similarity to ground truth. A second template is given to Chat GPT with a prompt that the original response is correct, and measures whether previous Chat GPT's response is similar.
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback import GroundTruthAgreement\ngolden_set = [\n {\"query\": \"who invented the lightbulb?\", \"response\": \"Thomas Edison\"},\n {\"query\": \"\u00bfquien invento la bombilla?\", \"response\": \"Thomas Edison\"}\n]\nground_truth_collection = GroundTruthAgreement(golden_set)\n\nfeedback = Feedback(ground_truth_collection.agreement_measure).on_input_output() \n
The
on_input_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
prompt str A text prompt to an agent.
required
response str The agent's response to the prompt.
required
Returns:
Type Description
Union[float, Tuple[float, Dict[str, str]]] - float: A value between 0 and 1. 0 being \"not in agreement\" and 1 being \"in agreement\".
Union[float, Tuple[float, Dict[str, str]]] - dict: with key 'ground_truth_response'
Source code in
trulens_eval/trulens_eval/feedback/groundtruth.py def agreement_measure(\n self, prompt: str, response: str\n) -> Union[float, Tuple[float, Dict[str, str]]]:\n \"\"\"\n Uses OpenAI's Chat GPT Model. A function that that measures\n similarity to ground truth. A second template is given to Chat GPT\n with a prompt that the original response is correct, and measures\n whether previous Chat GPT's response is similar.\n\n **Usage:**\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import GroundTruthAgreement\n golden_set = [\n {\"query\": \"who invented the lightbulb?\", \"response\": \"Thomas Edison\"},\n {\"query\": \"\u00bfquien invento la bombilla?\", \"response\": \"Thomas Edison\"}\n ]\n ground_truth_collection = GroundTruthAgreement(golden_set)\n\n feedback = Feedback(ground_truth_collection.agreement_measure).on_input_output() \n ```\n The `on_input_output()` selector can be changed. See [Feedback Function Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n prompt (str): A text prompt to an agent. \n response (str): The agent's response to the prompt.\n\n Returns:\n - float: A value between 0 and 1. 0 being \"not in agreement\" and 1\n being \"in agreement\".\n - dict: with key 'ground_truth_response'\n \"\"\"\n ground_truth_response = self._find_response(prompt)\n if ground_truth_response:\n agreement_txt = self.provider._get_answer_agreement(\n prompt, response, ground_truth_response\n )\n ret = re_0_10_rating(agreement_txt) / 10, dict(\n ground_truth_response=ground_truth_response\n )\n else:\n ret = np.nan\n\n return ret\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.groundtruth.GroundTruthAgreement.bert_score","title":"
bert_score(prompt, response)","text":"
Uses BERT Score. A function that that measures similarity to ground truth using bert embeddings.
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback import GroundTruthAgreement\ngolden_set = [\n {\"query\": \"who invented the lightbulb?\", \"response\": \"Thomas Edison\"},\n {\"query\": \"\u00bfquien invento la bombilla?\", \"response\": \"Thomas Edison\"}\n]\nground_truth_collection = GroundTruthAgreement(golden_set)\n\nfeedback = Feedback(ground_truth_collection.bert_score).on_input_output() \n
The
on_input_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
prompt str A text prompt to an agent.
required
response str The agent's response to the prompt.
required
Returns:
Type Description
Union[float, Tuple[float, Dict[str, str]]] - float: A value between 0 and 1. 0 being \"not in agreement\" and 1 being \"in agreement\".
Union[float, Tuple[float, Dict[str, str]]] - dict: with key 'ground_truth_response'
Source code in
trulens_eval/trulens_eval/feedback/groundtruth.py def bert_score(self, prompt: str,\n response: str) -> Union[float, Tuple[float, Dict[str, str]]]:\n \"\"\"\n Uses BERT Score. A function that that measures\n similarity to ground truth using bert embeddings. \n\n **Usage:**\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import GroundTruthAgreement\n golden_set = [\n {\"query\": \"who invented the lightbulb?\", \"response\": \"Thomas Edison\"},\n {\"query\": \"\u00bfquien invento la bombilla?\", \"response\": \"Thomas Edison\"}\n ]\n ground_truth_collection = GroundTruthAgreement(golden_set)\n\n feedback = Feedback(ground_truth_collection.bert_score).on_input_output() \n ```\n The `on_input_output()` selector can be changed. See [Feedback Function Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n\n Args:\n prompt (str): A text prompt to an agent.\n response (str): The agent's response to the prompt.\n\n Returns:\n - float: A value between 0 and 1. 0 being \"not in agreement\" and 1\n being \"in agreement\".\n - dict: with key 'ground_truth_response'\n \"\"\"\n if self.bert_scorer is None:\n self.bert_scorer = BERTScorer(lang=\"en\", rescale_with_baseline=True)\n ground_truth_response = self._find_response(prompt)\n if ground_truth_response:\n bert_score = self.bert_scorer.score(\n [response], [ground_truth_response]\n )\n ret = bert_score[0].item(), dict(\n ground_truth_response=ground_truth_response\n )\n else:\n ret = np.nan\n\n return ret\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.groundtruth.GroundTruthAgreement.bleu","title":"
bleu(prompt, response)","text":"
Uses BLEU Score. A function that that measures similarity to ground truth using token overlap.
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback import GroundTruthAgreement\ngolden_set = [\n {\"query\": \"who invented the lightbulb?\", \"response\": \"Thomas Edison\"},\n {\"query\": \"\u00bfquien invento la bombilla?\", \"response\": \"Thomas Edison\"}\n]\nground_truth_collection = GroundTruthAgreement(golden_set)\n\nfeedback = Feedback(ground_truth_collection.bleu).on_input_output() \n
The
on_input_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
prompt str A text prompt to an agent.
required
response str The agent's response to the prompt.
required
Returns:
Type Description
Union[float, Tuple[float, Dict[str, str]]] - float: A value between 0 and 1. 0 being \"not in agreement\" and 1 being \"in agreement\".
Union[float, Tuple[float, Dict[str, str]]] - dict: with key 'ground_truth_response'
Source code in
trulens_eval/trulens_eval/feedback/groundtruth.py def bleu(self, prompt: str,\n response: str) -> Union[float, Tuple[float, Dict[str, str]]]:\n \"\"\"\n Uses BLEU Score. A function that that measures\n similarity to ground truth using token overlap. \n\n **Usage:**\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import GroundTruthAgreement\n golden_set = [\n {\"query\": \"who invented the lightbulb?\", \"response\": \"Thomas Edison\"},\n {\"query\": \"\u00bfquien invento la bombilla?\", \"response\": \"Thomas Edison\"}\n ]\n ground_truth_collection = GroundTruthAgreement(golden_set)\n\n feedback = Feedback(ground_truth_collection.bleu).on_input_output() \n ```\n The `on_input_output()` selector can be changed. See [Feedback Function Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n prompt (str): A text prompt to an agent. \n response (str): The agent's response to the prompt.\n\n Returns:\n - float: A value between 0 and 1. 0 being \"not in agreement\" and 1\n being \"in agreement\".\n - dict: with key 'ground_truth_response'\n \"\"\"\n bleu = evaluate.load('bleu')\n ground_truth_response = self._find_response(prompt)\n if ground_truth_response:\n bleu_score = bleu.compute(\n predictions=[response], references=[ground_truth_response]\n )\n ret = bleu_score['bleu'], dict(\n ground_truth_response=ground_truth_response\n )\n else:\n ret = np.nan\n\n return ret\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.groundtruth.GroundTruthAgreement.mae","title":"
mae(prompt, response, score)","text":"
Method to look up the numeric expected score from a golden set and take the differnce.
Primarily used for evaluation of model generated feedback against human feedback
Usage
from trulens_eval import Feedback\nfrom trulens_eval.feedback import GroundTruthAgreement\n\ngolden_set =\n{\"query\": \"How many stomachs does a cow have?\", \"response\": \"Cows' diet relies primarily on grazing.\", \"expected_score\": 0.4},\n{\"query\": \"Name some top dental floss brands\", \"response\": \"I don't know\", \"expected_score\": 0.8}\n]\nground_truth_collection = GroundTruthAgreement(golden_set)\n\nf_groundtruth = Feedback(ground_truth.mae).on(Select.Record.calls[0].args.args[0]).on(Select.Record.calls[0].args.args[1]).on_output()\n
Source code in
trulens_eval/trulens_eval/feedback/groundtruth.py def mae(self, prompt: str, response: str, score: float) -> float:\n \"\"\"\n Method to look up the numeric expected score from a golden set and take the differnce.\n\n Primarily used for evaluation of model generated feedback against human feedback\n\n **Usage**\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import GroundTruthAgreement\n\n golden_set =\n {\"query\": \"How many stomachs does a cow have?\", \"response\": \"Cows' diet relies primarily on grazing.\", \"expected_score\": 0.4},\n {\"query\": \"Name some top dental floss brands\", \"response\": \"I don't know\", \"expected_score\": 0.8}\n ]\n ground_truth_collection = GroundTruthAgreement(golden_set)\n\n f_groundtruth = Feedback(ground_truth.mae).on(Select.Record.calls[0].args.args[0]).on(Select.Record.calls[0].args.args[1]).on_output()\n ```\n\n \"\"\"\n\n expected_score = self._find_score(prompt, response)\n if expected_score:\n ret = abs(float(score) - expected_score)\n expected_score = \"{:.2f}\".format(expected_score\n ).rstrip('0').rstrip('.')\n else:\n ret = np.nan\n return ret, {\"expected score\": expected_score}\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.groundtruth.GroundTruthAgreement.rouge","title":"
rouge(prompt, response)","text":"
Uses BLEU Score. A function that that measures similarity to ground truth using token overlap.
Parameters:
Name Type Description Default
prompt str A text prompt to an agent.
required
response str The agent's response to the prompt.
required
Returns:
Type Description
Union[float, Tuple[float, Dict[str, str]]] - float: A value between 0 and 1. 0 being \"not in agreement\" and 1 being \"in agreement\".
Union[float, Tuple[float, Dict[str, str]]] - dict: with key 'ground_truth_response'
Source code in
trulens_eval/trulens_eval/feedback/groundtruth.py def rouge(self, prompt: str,\n response: str) -> Union[float, Tuple[float, Dict[str, str]]]:\n \"\"\"\n Uses BLEU Score. A function that that measures\n similarity to ground truth using token overlap. \n\n Args:\n prompt (str): A text prompt to an agent. \n response (str): The agent's response to the prompt.\n\n Returns:\n - float: A value between 0 and 1. 0 being \"not in agreement\" and 1\n being \"in agreement\".\n - dict: with key 'ground_truth_response'\n \"\"\"\n rouge = evaluate.load('rouge')\n ground_truth_response = self._find_response(prompt)\n if ground_truth_response:\n rouge_score = rouge.compute(\n predictions=[response], references=[ground_truth_response]\n )\n ret = rouge_score['rouge1'], dict(\n ground_truth_response=ground_truth_response\n )\n else:\n ret = np.nan\n\n return ret\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.embeddings.Embeddings","title":"
Embeddings","text":"
Bases: SerialModel, WithClassInfo
Embedding related feedback function implementations.
Source code in
trulens_eval/trulens_eval/feedback/embeddings.py class Embeddings(SerialModel, WithClassInfo):\n \"\"\"Embedding related feedback function implementations.\n \"\"\"\n _embed_model: 'Embedder' = PrivateAttr()\n\n def __init__(self, embed_model: 'Embedder' = None):\n \"\"\"Instantiates embeddings for feedback functions. \n\n **Example Vector DB Creation:**\n ```\n vector_store = MilvusVectorStore(index_params={\n \"index_type\": \"IVF_FLAT\",\n \"metric_type\": \"L2\"\n },\n dim=384,\n search_params={\"nprobe\": 20},\n overwrite=True)\n llm = OpenAI(model=\"gpt-3.5-turbo\")\n embed_model = HuggingFaceEmbeddings(model_name = \"sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2\")\n storage_context = StorageContext.from_defaults(vector_store = vector_store)\n service_context = ServiceContext.from_defaults(embed_model = embed_model, llm = llm)\n index = VectorStoreIndex.from_documents(wiki_docs,\n service_context=service_context,\n storage_context=storage_context)\n query_engine = index.as_query_engine(top_k = 5)\n ```\n\n **Trulens Eval Instantiation:**\n ```\n f_embed = feedback.Embeddings(embed_model=embed_model)\n ```\n\n Args:\n embed_model ('Embedder'): Supported embedders taken from llama-index: https://gpt-index.readthedocs.io/en/latest/core_modules/model_modules/embeddings/root.html\n \"\"\"\n try:\n import sklearn\n except:\n raise ImportError(REQUIREMENT_SKLEARN)\n\n service_context = ServiceContext.from_defaults(embed_model=embed_model)\n self._embed_model = service_context.embed_model\n super().__init__(obj=self)\n\n def cosine_distance(\n self, query: str, document: str\n ) -> Union[float, Tuple[float, Dict[str, str]]]:\n \"\"\"\n Runs cosine distance on the query and document embeddings\n\n **Usage:**\n ```\n # Below is just one example. See supported embedders: https://gpt-index.readthedocs.io/en/latest/core_modules/model_modules/embeddings/root.html\n from langchain.embeddings.openai import OpenAIEmbeddings\n\n model_name = 'text-embedding-ada-002'\n\n embed_model = OpenAIEmbeddings(\n model=model_name,\n openai_api_key=OPENAI_API_KEY\n )\n\n # Create the feedback function\n f_embed = feedback.Embeddings(embed_model=embed_model)\n f_embed_dist = feedback.Feedback(f_embed.cosine_distance).on_input().on(Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content)\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Args:\n query (str): A text prompt to a vector DB. \n document (str): The document returned from the vector DB.\n\n Returns:\n - float: the embedding vector distance\n \"\"\"\n import sklearn\n query_embed = np.asarray(\n self._embed_model.get_query_embedding(query)\n ).reshape(\n 1, -1\n ) # sklearn expects 2d array (first dimension number of samples)\n document_embed = np.asarray(\n self._embed_model.get_text_embedding(document)\n ).reshape(\n 1, -1\n ) # sklearn expects 2d array (first dimension number of samples)\n\n return sklearn.metrics.pairwise.cosine_distances(\n query_embed, document_embed\n )[0][\n 0\n ] # final results will be dimensions (sample query x sample doc) === (1,1)\n\n def manhattan_distance(\n self, query: str, document: str\n ) -> Union[float, Tuple[float, Dict[str, str]]]:\n \"\"\"\n Runs L1 distance on the query and document embeddings\n\n **Usage:**\n ```\n # Below is just one example. See supported embedders: https://gpt-index.readthedocs.io/en/latest/core_modules/model_modules/embeddings/root.html\n from langchain.embeddings.openai import OpenAIEmbeddings\n\n model_name = 'text-embedding-ada-002'\n\n embed_model = OpenAIEmbeddings(\n model=model_name,\n openai_api_key=OPENAI_API_KEY\n )\n\n # Create the feedback function\n f_embed = feedback.Embeddings(embed_model=embed_model)\n f_embed_dist = feedback.Feedback(f_embed.manhattan_distance).on_input().on(Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content)\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Args:\n query (str): A text prompt to a vector DB. \n document (str): The document returned from the vector DB.\n\n Returns:\n - float: the embedding vector distance\n \"\"\"\n import sklearn\n query_embed = np.asarray(\n self._embed_model.get_query_embedding(query)\n ).reshape(\n 1, -1\n ) # sklearn expects 2d array (first dimension number of samples)\n document_embed = np.asarray(\n self._embed_model.get_text_embedding(document)\n ).reshape(\n 1, -1\n ) # sklearn expects 2d array (first dimension number of samples)\n\n return sklearn.metrics.pairwise.manhattan_distances(\n query_embed, document_embed\n )[0][\n 0\n ] # final results will be dimensions (sample query x sample doc) === (1,1)\n\n def euclidean_distance(\n self, query: str, document: str\n ) -> Union[float, Tuple[float, Dict[str, str]]]:\n \"\"\"\n Runs L2 distance on the query and document embeddings\n\n **Usage:**\n ```\n # Below is just one example. See supported embedders: https://gpt-index.readthedocs.io/en/latest/core_modules/model_modules/embeddings/root.html\n from langchain.embeddings.openai import OpenAIEmbeddings\n\n model_name = 'text-embedding-ada-002'\n\n embed_model = OpenAIEmbeddings(\n model=model_name,\n openai_api_key=OPENAI_API_KEY\n )\n\n # Create the feedback function\n f_embed = feedback.Embeddings(embed_model=embed_model)\n f_embed_dist = feedback.Feedback(f_embed.euclidean_distance).on_input().on(Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content)\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Args:\n query (str): A text prompt to a vector DB. \n document (str): The document returned from the vector DB.\n\n Returns:\n - float: the embedding vector distance\n \"\"\"\n import sklearn\n query_embed = np.asarray(\n self._embed_model.get_query_embedding(query)\n ).reshape(\n 1, -1\n ) # sklearn expects 2d array (first dimension number of samples)\n document_embed = np.asarray(\n self._embed_model.get_text_embedding(document)\n ).reshape(\n 1, -1\n ) # sklearn expects 2d array (first dimension number of samples)\n\n return sklearn.metrics.pairwise.euclidean_distances(\n query_embed, document_embed\n )[0][\n 0\n ] # final results will be dimensions (sample query x sample doc) === (1,1)\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.embeddings.Embeddings.__init__","title":"
__init__(embed_model=None)","text":"
Instantiates embeddings for feedback functions.
Example Vector DB Creation:
vector_store = MilvusVectorStore(index_params={\n \"index_type\": \"IVF_FLAT\",\n \"metric_type\": \"L2\"\n },\n dim=384,\n search_params={\"nprobe\": 20},\n overwrite=True)\nllm = OpenAI(model=\"gpt-3.5-turbo\")\nembed_model = HuggingFaceEmbeddings(model_name = \"sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2\")\nstorage_context = StorageContext.from_defaults(vector_store = vector_store)\nservice_context = ServiceContext.from_defaults(embed_model = embed_model, llm = llm)\nindex = VectorStoreIndex.from_documents(wiki_docs,\n service_context=service_context,\n storage_context=storage_context)\nquery_engine = index.as_query_engine(top_k = 5)\n
Trulens Eval Instantiation:
f_embed = feedback.Embeddings(embed_model=embed_model)\n
Parameters:
Name Type Description Default
embed_model Embedder Supported embedders taken from llama-index: https://gpt-index.readthedocs.io/en/latest/core_modules/model_modules/embeddings/root.html
None Source code in
trulens_eval/trulens_eval/feedback/embeddings.py def __init__(self, embed_model: 'Embedder' = None):\n \"\"\"Instantiates embeddings for feedback functions. \n\n **Example Vector DB Creation:**\n ```\n vector_store = MilvusVectorStore(index_params={\n \"index_type\": \"IVF_FLAT\",\n \"metric_type\": \"L2\"\n },\n dim=384,\n search_params={\"nprobe\": 20},\n overwrite=True)\n llm = OpenAI(model=\"gpt-3.5-turbo\")\n embed_model = HuggingFaceEmbeddings(model_name = \"sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2\")\n storage_context = StorageContext.from_defaults(vector_store = vector_store)\n service_context = ServiceContext.from_defaults(embed_model = embed_model, llm = llm)\n index = VectorStoreIndex.from_documents(wiki_docs,\n service_context=service_context,\n storage_context=storage_context)\n query_engine = index.as_query_engine(top_k = 5)\n ```\n\n **Trulens Eval Instantiation:**\n ```\n f_embed = feedback.Embeddings(embed_model=embed_model)\n ```\n\n Args:\n embed_model ('Embedder'): Supported embedders taken from llama-index: https://gpt-index.readthedocs.io/en/latest/core_modules/model_modules/embeddings/root.html\n \"\"\"\n try:\n import sklearn\n except:\n raise ImportError(REQUIREMENT_SKLEARN)\n\n service_context = ServiceContext.from_defaults(embed_model=embed_model)\n self._embed_model = service_context.embed_model\n super().__init__(obj=self)\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.embeddings.Embeddings.cosine_distance","title":"
cosine_distance(query, document)","text":"
Runs cosine distance on the query and document embeddings
Usage:
# Below is just one example. See supported embedders: https://gpt-index.readthedocs.io/en/latest/core_modules/model_modules/embeddings/root.html\nfrom langchain.embeddings.openai import OpenAIEmbeddings\n\nmodel_name = 'text-embedding-ada-002'\n\nembed_model = OpenAIEmbeddings(\n model=model_name,\n openai_api_key=OPENAI_API_KEY\n)\n\n# Create the feedback function\nf_embed = feedback.Embeddings(embed_model=embed_model)\nf_embed_dist = feedback.Feedback(f_embed.cosine_distance).on_input().on(Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content)\n
The
on(...) selector can be changed. See Feedback Function Guide : Selectors
Parameters:
Name Type Description Default
query str A text prompt to a vector DB.
required
document str The document returned from the vector DB.
required
Returns:
Type Description
Union[float, Tuple[float, Dict[str, str]]] - float: the embedding vector distance
Source code in
trulens_eval/trulens_eval/feedback/embeddings.py def cosine_distance(\n self, query: str, document: str\n) -> Union[float, Tuple[float, Dict[str, str]]]:\n \"\"\"\n Runs cosine distance on the query and document embeddings\n\n **Usage:**\n ```\n # Below is just one example. See supported embedders: https://gpt-index.readthedocs.io/en/latest/core_modules/model_modules/embeddings/root.html\n from langchain.embeddings.openai import OpenAIEmbeddings\n\n model_name = 'text-embedding-ada-002'\n\n embed_model = OpenAIEmbeddings(\n model=model_name,\n openai_api_key=OPENAI_API_KEY\n )\n\n # Create the feedback function\n f_embed = feedback.Embeddings(embed_model=embed_model)\n f_embed_dist = feedback.Feedback(f_embed.cosine_distance).on_input().on(Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content)\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Args:\n query (str): A text prompt to a vector DB. \n document (str): The document returned from the vector DB.\n\n Returns:\n - float: the embedding vector distance\n \"\"\"\n import sklearn\n query_embed = np.asarray(\n self._embed_model.get_query_embedding(query)\n ).reshape(\n 1, -1\n ) # sklearn expects 2d array (first dimension number of samples)\n document_embed = np.asarray(\n self._embed_model.get_text_embedding(document)\n ).reshape(\n 1, -1\n ) # sklearn expects 2d array (first dimension number of samples)\n\n return sklearn.metrics.pairwise.cosine_distances(\n query_embed, document_embed\n )[0][\n 0\n ] # final results will be dimensions (sample query x sample doc) === (1,1)\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.embeddings.Embeddings.euclidean_distance","title":"
euclidean_distance(query, document)","text":"
Runs L2 distance on the query and document embeddings
Usage:
# Below is just one example. See supported embedders: https://gpt-index.readthedocs.io/en/latest/core_modules/model_modules/embeddings/root.html\nfrom langchain.embeddings.openai import OpenAIEmbeddings\n\nmodel_name = 'text-embedding-ada-002'\n\nembed_model = OpenAIEmbeddings(\n model=model_name,\n openai_api_key=OPENAI_API_KEY\n)\n\n# Create the feedback function\nf_embed = feedback.Embeddings(embed_model=embed_model)\nf_embed_dist = feedback.Feedback(f_embed.euclidean_distance).on_input().on(Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content)\n
The
on(...) selector can be changed. See Feedback Function Guide : Selectors
Parameters:
Name Type Description Default
query str A text prompt to a vector DB.
required
document str The document returned from the vector DB.
required
Returns:
Type Description
Union[float, Tuple[float, Dict[str, str]]] - float: the embedding vector distance
Source code in
trulens_eval/trulens_eval/feedback/embeddings.py def euclidean_distance(\n self, query: str, document: str\n) -> Union[float, Tuple[float, Dict[str, str]]]:\n \"\"\"\n Runs L2 distance on the query and document embeddings\n\n **Usage:**\n ```\n # Below is just one example. See supported embedders: https://gpt-index.readthedocs.io/en/latest/core_modules/model_modules/embeddings/root.html\n from langchain.embeddings.openai import OpenAIEmbeddings\n\n model_name = 'text-embedding-ada-002'\n\n embed_model = OpenAIEmbeddings(\n model=model_name,\n openai_api_key=OPENAI_API_KEY\n )\n\n # Create the feedback function\n f_embed = feedback.Embeddings(embed_model=embed_model)\n f_embed_dist = feedback.Feedback(f_embed.euclidean_distance).on_input().on(Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content)\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Args:\n query (str): A text prompt to a vector DB. \n document (str): The document returned from the vector DB.\n\n Returns:\n - float: the embedding vector distance\n \"\"\"\n import sklearn\n query_embed = np.asarray(\n self._embed_model.get_query_embedding(query)\n ).reshape(\n 1, -1\n ) # sklearn expects 2d array (first dimension number of samples)\n document_embed = np.asarray(\n self._embed_model.get_text_embedding(document)\n ).reshape(\n 1, -1\n ) # sklearn expects 2d array (first dimension number of samples)\n\n return sklearn.metrics.pairwise.euclidean_distances(\n query_embed, document_embed\n )[0][\n 0\n ] # final results will be dimensions (sample query x sample doc) === (1,1)\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.embeddings.Embeddings.manhattan_distance","title":"
manhattan_distance(query, document)","text":"
Runs L1 distance on the query and document embeddings
Usage:
# Below is just one example. See supported embedders: https://gpt-index.readthedocs.io/en/latest/core_modules/model_modules/embeddings/root.html\nfrom langchain.embeddings.openai import OpenAIEmbeddings\n\nmodel_name = 'text-embedding-ada-002'\n\nembed_model = OpenAIEmbeddings(\n model=model_name,\n openai_api_key=OPENAI_API_KEY\n)\n\n# Create the feedback function\nf_embed = feedback.Embeddings(embed_model=embed_model)\nf_embed_dist = feedback.Feedback(f_embed.manhattan_distance).on_input().on(Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content)\n
The
on(...) selector can be changed. See Feedback Function Guide : Selectors
Parameters:
Name Type Description Default
query str A text prompt to a vector DB.
required
document str The document returned from the vector DB.
required
Returns:
Type Description
Union[float, Tuple[float, Dict[str, str]]] - float: the embedding vector distance
Source code in
trulens_eval/trulens_eval/feedback/embeddings.py def manhattan_distance(\n self, query: str, document: str\n) -> Union[float, Tuple[float, Dict[str, str]]]:\n \"\"\"\n Runs L1 distance on the query and document embeddings\n\n **Usage:**\n ```\n # Below is just one example. See supported embedders: https://gpt-index.readthedocs.io/en/latest/core_modules/model_modules/embeddings/root.html\n from langchain.embeddings.openai import OpenAIEmbeddings\n\n model_name = 'text-embedding-ada-002'\n\n embed_model = OpenAIEmbeddings(\n model=model_name,\n openai_api_key=OPENAI_API_KEY\n )\n\n # Create the feedback function\n f_embed = feedback.Embeddings(embed_model=embed_model)\n f_embed_dist = feedback.Feedback(f_embed.manhattan_distance).on_input().on(Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content)\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Args:\n query (str): A text prompt to a vector DB. \n document (str): The document returned from the vector DB.\n\n Returns:\n - float: the embedding vector distance\n \"\"\"\n import sklearn\n query_embed = np.asarray(\n self._embed_model.get_query_embedding(query)\n ).reshape(\n 1, -1\n ) # sklearn expects 2d array (first dimension number of samples)\n document_embed = np.asarray(\n self._embed_model.get_text_embedding(document)\n ).reshape(\n 1, -1\n ) # sklearn expects 2d array (first dimension number of samples)\n\n return sklearn.metrics.pairwise.manhattan_distances(\n query_embed, document_embed\n )[0][\n 0\n ] # final results will be dimensions (sample query x sample doc) === (1,1)\n
"},{"location":"trulens_eval/api/huggingface_provider/","title":"LiteLLM APIs","text":"
Below is how you can instantiate HuggingFace as a provider, along with feedback functions available only from HuggingFace.
Bases: Provider
Out of the box feedback functions calling Huggingface APIs.
Source code in
trulens_eval/trulens_eval/feedback/provider/hugs.py class Huggingface(Provider):\n \"\"\"\n Out of the box feedback functions calling Huggingface APIs.\n \"\"\"\n\n endpoint: Endpoint\n\n def __init__(self, name: Optional[str] = None, endpoint=None, **kwargs):\n # NOTE(piotrm): pydantic adds endpoint to the signature of this\n # constructor if we don't include it explicitly, even though we set it\n # down below. Adding it as None here as a temporary hack.\n \"\"\"\n Create a Huggingface Provider with out of the box feedback functions.\n\n **Usage:**\n ```python\n from trulens_eval.feedback.provider.hugs import Huggingface\n huggingface_provider = Huggingface()\n ```\n\n Args:\n endpoint (Endpoint): Internal Usage for DB serialization\n \"\"\"\n\n kwargs['name'] = name\n\n self_kwargs = dict()\n\n # TODO: figure out why all of this logic is necessary:\n if endpoint is None:\n self_kwargs['endpoint'] = HuggingfaceEndpoint(**kwargs)\n else:\n if isinstance(endpoint, Endpoint):\n self_kwargs['endpoint'] = endpoint\n else:\n self_kwargs['endpoint'] = HuggingfaceEndpoint(**endpoint)\n\n self_kwargs['name'] = name or \"huggingface\"\n\n super().__init__(\n **self_kwargs\n ) # need to include pydantic.BaseModel.__init__\n\n # TODEP\n @_tci\n def language_match(self, text1: str, text2: str) -> Tuple[float, Dict]:\n \"\"\"\n Uses Huggingface's papluca/xlm-roberta-base-language-detection model. A\n function that uses language detection on `text1` and `text2` and\n calculates the probit difference on the language detected on text1. The\n function is: `1.0 - (|probit_language_text1(text1) -\n probit_language_text1(text2))`\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.hugs import Huggingface\n huggingface_provider = Huggingface()\n\n feedback = Feedback(huggingface_provider.language_match).on_input_output() \n ```\n The `on_input_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text1 (str): Text to evaluate.\n text2 (str): Comparative text to evaluate.\n\n Returns:\n\n float: A value between 0 and 1. 0 being \"different languages\" and 1\n being \"same languages\".\n \"\"\"\n\n def get_scores(text):\n payload = {\"inputs\": text}\n hf_response = self.endpoint.post(\n url=HUGS_LANGUAGE_API_URL, payload=payload, timeout=30\n )\n return {r['label']: r['score'] for r in hf_response}\n\n with ThreadPoolExecutor(max_workers=2) as tpool:\n max_length = 500\n f_scores1: Future[Dict] = tpool.submit(\n get_scores, text=text1[:max_length]\n )\n f_scores2: Future[Dict] = tpool.submit(\n get_scores, text=text2[:max_length]\n )\n\n wait([f_scores1, f_scores2])\n\n scores1: Dict = f_scores1.result()\n scores2: Dict = f_scores2.result()\n\n langs = list(scores1.keys())\n prob1 = np.array([scores1[k] for k in langs])\n prob2 = np.array([scores2[k] for k in langs])\n diff = prob1 - prob2\n\n l1: float = float(1.0 - (np.linalg.norm(diff, ord=1)) / 2.0)\n\n return l1, dict(text1_scores=scores1, text2_scores=scores2)\n\n # TODEP\n @_tci\n def positive_sentiment(self, text: str) -> float:\n \"\"\"\n Uses Huggingface's cardiffnlp/twitter-roberta-base-sentiment model. A\n function that uses a sentiment classifier on `text`.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.hugs import Huggingface\n huggingface_provider = Huggingface()\n\n feedback = Feedback(huggingface_provider.positive_sentiment).on_output() \n ```\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0 and 1. 0 being \"negative sentiment\" and 1\n being \"positive sentiment\".\n \"\"\"\n\n max_length = 500\n truncated_text = text[:max_length]\n payload = {\"inputs\": truncated_text}\n\n hf_response = self.endpoint.post(\n url=HUGS_SENTIMENT_API_URL, payload=payload\n )\n\n for label in hf_response:\n if label['label'] == 'LABEL_2':\n return float(label['score'])\n\n raise RuntimeError(\"LABEL_2 not found in huggingface api response.\")\n\n # TODEP\n @_tci\n def not_toxic(self, text: str) -> float:\n \"\"\"\n Uses Huggingface's martin-ha/toxic-comment-model model. A function that\n uses a toxic comment classifier on `text`.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.hugs import Huggingface\n huggingface_provider = Huggingface()\n\n feedback = Feedback(huggingface_provider.not_toxic).on_output() \n ```\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0 and 1. 0 being \"toxic\" and 1 being \"not\n toxic\".\n \"\"\"\n\n assert len(text) > 0, \"Input cannot be blank.\"\n\n max_length = 500\n truncated_text = text[:max_length]\n payload = {\"inputs\": truncated_text}\n hf_response = self.endpoint.post(\n url=HUGS_TOXIC_API_URL, payload=payload\n )\n\n for label in hf_response:\n if label['label'] == 'toxic':\n return label['score']\n\n raise RuntimeError(\"LABEL_2 not found in huggingface api response.\")\n\n # TODEP\n @_tci\n def _summarized_groundedness(self, premise: str, hypothesis: str) -> float:\n \"\"\" A groundedness measure best used for summarized premise against simple hypothesis.\n This Huggingface implementation uses NLI.\n\n Args:\n premise (str): NLI Premise\n hypothesis (str): NLI Hypothesis\n\n Returns:\n float: NLI Entailment\n \"\"\"\n\n if not '.' == premise[len(premise) - 1]:\n premise = premise + '.'\n nli_string = premise + ' ' + hypothesis\n payload = {\"inputs\": nli_string}\n hf_response = self.endpoint.post(url=HUGS_NLI_API_URL, payload=payload)\n\n for label in hf_response:\n if label['label'] == 'entailment':\n return label['score']\n\n raise RuntimeError(\"LABEL_2 not found in huggingface api response.\")\n\n # TODEP\n @_tci\n def _doc_groundedness(self, premise: str, hypothesis: str) -> float:\n \"\"\"\n A groundedness measure for full document premise against hypothesis.\n This Huggingface implementation uses DocNLI. The Hypoethsis still only\n works on single small hypothesis.\n\n Args:\n premise (str): NLI Premise\n hypothesis (str): NLI Hypothesis\n\n Returns:\n float: NLI Entailment\n \"\"\"\n nli_string = premise + ' [SEP] ' + hypothesis\n payload = {\"inputs\": nli_string}\n hf_response = self.endpoint.post(\n url=HUGS_DOCNLI_API_URL, payload=payload\n )\n\n for label in hf_response:\n if label['label'] == 'entailment':\n return label['score']\n\n def pii_detection(self, text: str) -> float:\n \"\"\"\n NER model to detect PII.\n **Usage:**\n ```\n hugs = Huggingface()\n\n # Define a pii_detection feedback function using HuggingFace.\n f_pii_detection = Feedback(hugs.pii_detection).on_input()\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Args:\n input (str): A text prompt that may contain a name.\n\n Returns:\n - float: the likelihood that a name is contained in the input text.\n \"\"\"\n\n # Initialize a list to store scores for \"NAME\" entities\n likelihood_scores = []\n\n payload = {\"inputs\": text}\n\n hf_response = self.endpoint.post(\n url=HUGS_PII_DETECTION_API_URL, payload=payload\n )\n\n # If the response is a dictionary, convert it to a list. This is for when only one name is identified.\n if isinstance(hf_response, dict):\n hf_response = [hf_response]\n\n if not isinstance(hf_response, list):\n raise ValueError(\n f\"Unexpected response from Huggingface API: {hf_response}\"\n )\n\n # Iterate through the entities and extract scores for \"NAME\" entities\n for entity in hf_response:\n likelihood_scores.append(entity[\"score\"])\n\n # Calculate the sum of all individual likelihood scores (P(A) + P(B) + ...)\n sum_individual_probabilities = sum(likelihood_scores)\n\n # Initialize the total likelihood for at least one name\n total_likelihood = sum_individual_probabilities\n\n # Calculate the product of pairwise likelihood scores (P(A and B), P(A and C), ...)\n for i in range(len(likelihood_scores)):\n for j in range(i + 1, len(likelihood_scores)):\n pairwise_likelihood = likelihood_scores[i] * likelihood_scores[j]\n total_likelihood -= pairwise_likelihood\n\n score = 1 - total_likelihood\n\n return score\n\n def pii_detection_with_cot_reasons(self, text: str):\n \"\"\"\n NER model to detect PII, with reasons.\n\n **Usage:**\n ```\n hugs = Huggingface()\n\n # Define a pii_detection feedback function using HuggingFace.\n f_pii_detection = Feedback(hugs.pii_detection).on_input()\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n \"\"\"\n\n # Initialize a dictionary to store reasons\n reasons = {}\n\n # Initialize a list to store scores for \"NAME\" entities\n likelihood_scores = []\n\n payload = {\"inputs\": text}\n\n try:\n hf_response = self.endpoint.post(\n url=HUGS_PII_DETECTION_API_URL, payload=payload\n )\n\n # TODO: Make error handling more granular so it's not swallowed.\n except Exception as e:\n logger.debug(\"No PII was found\")\n hf_response = [\n {\n \"entity_group\": \"NONE\",\n \"score\": 0.0,\n \"word\": np.nan,\n \"start\": np.nan,\n \"end\": np.nan\n }\n ]\n\n # Convert the response to a list if it's not already a list\n if not isinstance(hf_response, list):\n hf_response = [hf_response]\n\n # Check if the response is a list\n if not isinstance(hf_response, list):\n raise ValueError(\n \"Unexpected response from Huggingface API: response should be a list or a dictionary\"\n )\n\n # Iterate through the entities and extract \"word\" and \"score\" for \"NAME\" entities\n for i, entity in enumerate(hf_response):\n reasons[f\"{entity.get('entity_group')} detected: {entity['word']}\"\n ] = f\"PII Likelihood: {entity['score']}\"\n likelihood_scores.append(entity[\"score\"])\n\n # Calculate the sum of all individual likelihood scores (P(A) + P(B) + ...)\n sum_individual_probabilities = sum(likelihood_scores)\n\n # Initialize the total likelihood for at least one name\n total_likelihood = sum_individual_probabilities\n\n # Calculate the product of pairwise likelihood scores (P(A and B), P(A and C), ...)\n for i in range(len(likelihood_scores)):\n for j in range(i + 1, len(likelihood_scores)):\n pairwise_likelihood = likelihood_scores[i] * likelihood_scores[j]\n total_likelihood -= pairwise_likelihood\n\n score = 1 - total_likelihood\n\n return score, reasons\n
"},{"location":"trulens_eval/api/huggingface_provider/#trulens_eval.trulens_eval.feedback.provider.hugs.Huggingface.__init__","title":"
__init__(name=None, endpoint=None, **kwargs)","text":"
Create a Huggingface Provider with out of the box feedback functions.
Usage:
from trulens_eval.feedback.provider.hugs import Huggingface\nhuggingface_provider = Huggingface()\n
Parameters:
Name Type Description Default
endpoint Endpoint Internal Usage for DB serialization
None Source code in
trulens_eval/trulens_eval/feedback/provider/hugs.py def __init__(self, name: Optional[str] = None, endpoint=None, **kwargs):\n # NOTE(piotrm): pydantic adds endpoint to the signature of this\n # constructor if we don't include it explicitly, even though we set it\n # down below. Adding it as None here as a temporary hack.\n \"\"\"\n Create a Huggingface Provider with out of the box feedback functions.\n\n **Usage:**\n ```python\n from trulens_eval.feedback.provider.hugs import Huggingface\n huggingface_provider = Huggingface()\n ```\n\n Args:\n endpoint (Endpoint): Internal Usage for DB serialization\n \"\"\"\n\n kwargs['name'] = name\n\n self_kwargs = dict()\n\n # TODO: figure out why all of this logic is necessary:\n if endpoint is None:\n self_kwargs['endpoint'] = HuggingfaceEndpoint(**kwargs)\n else:\n if isinstance(endpoint, Endpoint):\n self_kwargs['endpoint'] = endpoint\n else:\n self_kwargs['endpoint'] = HuggingfaceEndpoint(**endpoint)\n\n self_kwargs['name'] = name or \"huggingface\"\n\n super().__init__(\n **self_kwargs\n ) # need to include pydantic.BaseModel.__init__\n
"},{"location":"trulens_eval/api/huggingface_provider/#trulens_eval.trulens_eval.feedback.provider.hugs.Huggingface.language_match","title":"
language_match(text1, text2)","text":"
Uses Huggingface's papluca/xlm-roberta-base-language-detection model. A function that uses language detection on text1 and text2 and calculates the probit difference on the language detected on text1. The function is: 1.0 - (|probit_language_text1(text1) - probit_language_text1(text2))
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback.provider.hugs import Huggingface\nhuggingface_provider = Huggingface()\n\nfeedback = Feedback(huggingface_provider.language_match).on_input_output() \n
The
on_input_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text1 str Text to evaluate.
required
text2 str Comparative text to evaluate.
required
Returns:
float: A value between 0 and 1. 0 being \"different languages\" and 1\nbeing \"same languages\".\n
Source code in
trulens_eval/trulens_eval/feedback/provider/hugs.py @_tci\ndef language_match(self, text1: str, text2: str) -> Tuple[float, Dict]:\n \"\"\"\n Uses Huggingface's papluca/xlm-roberta-base-language-detection model. A\n function that uses language detection on `text1` and `text2` and\n calculates the probit difference on the language detected on text1. The\n function is: `1.0 - (|probit_language_text1(text1) -\n probit_language_text1(text2))`\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.hugs import Huggingface\n huggingface_provider = Huggingface()\n\n feedback = Feedback(huggingface_provider.language_match).on_input_output() \n ```\n The `on_input_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text1 (str): Text to evaluate.\n text2 (str): Comparative text to evaluate.\n\n Returns:\n\n float: A value between 0 and 1. 0 being \"different languages\" and 1\n being \"same languages\".\n \"\"\"\n\n def get_scores(text):\n payload = {\"inputs\": text}\n hf_response = self.endpoint.post(\n url=HUGS_LANGUAGE_API_URL, payload=payload, timeout=30\n )\n return {r['label']: r['score'] for r in hf_response}\n\n with ThreadPoolExecutor(max_workers=2) as tpool:\n max_length = 500\n f_scores1: Future[Dict] = tpool.submit(\n get_scores, text=text1[:max_length]\n )\n f_scores2: Future[Dict] = tpool.submit(\n get_scores, text=text2[:max_length]\n )\n\n wait([f_scores1, f_scores2])\n\n scores1: Dict = f_scores1.result()\n scores2: Dict = f_scores2.result()\n\n langs = list(scores1.keys())\n prob1 = np.array([scores1[k] for k in langs])\n prob2 = np.array([scores2[k] for k in langs])\n diff = prob1 - prob2\n\n l1: float = float(1.0 - (np.linalg.norm(diff, ord=1)) / 2.0)\n\n return l1, dict(text1_scores=scores1, text2_scores=scores2)\n
"},{"location":"trulens_eval/api/huggingface_provider/#trulens_eval.trulens_eval.feedback.provider.hugs.Huggingface.not_toxic","title":"
not_toxic(text)","text":"
Uses Huggingface's martin-ha/toxic-comment-model model. A function that uses a toxic comment classifier on text.
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback.provider.hugs import Huggingface\nhuggingface_provider = Huggingface()\n\nfeedback = Feedback(huggingface_provider.not_toxic).on_output() \n
The
on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str Text to evaluate.
required
Returns:
Name Type Description
float float A value between 0 and 1. 0 being \"toxic\" and 1 being \"not
float toxic\".
Source code in
trulens_eval/trulens_eval/feedback/provider/hugs.py @_tci\ndef not_toxic(self, text: str) -> float:\n \"\"\"\n Uses Huggingface's martin-ha/toxic-comment-model model. A function that\n uses a toxic comment classifier on `text`.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.hugs import Huggingface\n huggingface_provider = Huggingface()\n\n feedback = Feedback(huggingface_provider.not_toxic).on_output() \n ```\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0 and 1. 0 being \"toxic\" and 1 being \"not\n toxic\".\n \"\"\"\n\n assert len(text) > 0, \"Input cannot be blank.\"\n\n max_length = 500\n truncated_text = text[:max_length]\n payload = {\"inputs\": truncated_text}\n hf_response = self.endpoint.post(\n url=HUGS_TOXIC_API_URL, payload=payload\n )\n\n for label in hf_response:\n if label['label'] == 'toxic':\n return label['score']\n\n raise RuntimeError(\"LABEL_2 not found in huggingface api response.\")\n
"},{"location":"trulens_eval/api/huggingface_provider/#trulens_eval.trulens_eval.feedback.provider.hugs.Huggingface.pii_detection","title":"
pii_detection(text)","text":"
NER model to detect PII. Usage:
hugs = Huggingface()\n\n# Define a pii_detection feedback function using HuggingFace.\nf_pii_detection = Feedback(hugs.pii_detection).on_input()\n
The
on(...) selector can be changed. See Feedback Function Guide : Selectors
Parameters:
Name Type Description Default
input str A text prompt that may contain a name.
required
Returns:
Type Description
float - float: the likelihood that a name is contained in the input text.
Source code in
trulens_eval/trulens_eval/feedback/provider/hugs.py def pii_detection(self, text: str) -> float:\n \"\"\"\n NER model to detect PII.\n **Usage:**\n ```\n hugs = Huggingface()\n\n # Define a pii_detection feedback function using HuggingFace.\n f_pii_detection = Feedback(hugs.pii_detection).on_input()\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Args:\n input (str): A text prompt that may contain a name.\n\n Returns:\n - float: the likelihood that a name is contained in the input text.\n \"\"\"\n\n # Initialize a list to store scores for \"NAME\" entities\n likelihood_scores = []\n\n payload = {\"inputs\": text}\n\n hf_response = self.endpoint.post(\n url=HUGS_PII_DETECTION_API_URL, payload=payload\n )\n\n # If the response is a dictionary, convert it to a list. This is for when only one name is identified.\n if isinstance(hf_response, dict):\n hf_response = [hf_response]\n\n if not isinstance(hf_response, list):\n raise ValueError(\n f\"Unexpected response from Huggingface API: {hf_response}\"\n )\n\n # Iterate through the entities and extract scores for \"NAME\" entities\n for entity in hf_response:\n likelihood_scores.append(entity[\"score\"])\n\n # Calculate the sum of all individual likelihood scores (P(A) + P(B) + ...)\n sum_individual_probabilities = sum(likelihood_scores)\n\n # Initialize the total likelihood for at least one name\n total_likelihood = sum_individual_probabilities\n\n # Calculate the product of pairwise likelihood scores (P(A and B), P(A and C), ...)\n for i in range(len(likelihood_scores)):\n for j in range(i + 1, len(likelihood_scores)):\n pairwise_likelihood = likelihood_scores[i] * likelihood_scores[j]\n total_likelihood -= pairwise_likelihood\n\n score = 1 - total_likelihood\n\n return score\n
"},{"location":"trulens_eval/api/huggingface_provider/#trulens_eval.trulens_eval.feedback.provider.hugs.Huggingface.pii_detection_with_cot_reasons","title":"
pii_detection_with_cot_reasons(text)","text":"
NER model to detect PII, with reasons.
Usage:
hugs = Huggingface()\n\n# Define a pii_detection feedback function using HuggingFace.\nf_pii_detection = Feedback(hugs.pii_detection).on_input()\n
The
on(...) selector can be changed. See Feedback Function Guide : Selectors Source code in
trulens_eval/trulens_eval/feedback/provider/hugs.py def pii_detection_with_cot_reasons(self, text: str):\n \"\"\"\n NER model to detect PII, with reasons.\n\n **Usage:**\n ```\n hugs = Huggingface()\n\n # Define a pii_detection feedback function using HuggingFace.\n f_pii_detection = Feedback(hugs.pii_detection).on_input()\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n \"\"\"\n\n # Initialize a dictionary to store reasons\n reasons = {}\n\n # Initialize a list to store scores for \"NAME\" entities\n likelihood_scores = []\n\n payload = {\"inputs\": text}\n\n try:\n hf_response = self.endpoint.post(\n url=HUGS_PII_DETECTION_API_URL, payload=payload\n )\n\n # TODO: Make error handling more granular so it's not swallowed.\n except Exception as e:\n logger.debug(\"No PII was found\")\n hf_response = [\n {\n \"entity_group\": \"NONE\",\n \"score\": 0.0,\n \"word\": np.nan,\n \"start\": np.nan,\n \"end\": np.nan\n }\n ]\n\n # Convert the response to a list if it's not already a list\n if not isinstance(hf_response, list):\n hf_response = [hf_response]\n\n # Check if the response is a list\n if not isinstance(hf_response, list):\n raise ValueError(\n \"Unexpected response from Huggingface API: response should be a list or a dictionary\"\n )\n\n # Iterate through the entities and extract \"word\" and \"score\" for \"NAME\" entities\n for i, entity in enumerate(hf_response):\n reasons[f\"{entity.get('entity_group')} detected: {entity['word']}\"\n ] = f\"PII Likelihood: {entity['score']}\"\n likelihood_scores.append(entity[\"score\"])\n\n # Calculate the sum of all individual likelihood scores (P(A) + P(B) + ...)\n sum_individual_probabilities = sum(likelihood_scores)\n\n # Initialize the total likelihood for at least one name\n total_likelihood = sum_individual_probabilities\n\n # Calculate the product of pairwise likelihood scores (P(A and B), P(A and C), ...)\n for i in range(len(likelihood_scores)):\n for j in range(i + 1, len(likelihood_scores)):\n pairwise_likelihood = likelihood_scores[i] * likelihood_scores[j]\n total_likelihood -= pairwise_likelihood\n\n score = 1 - total_likelihood\n\n return score, reasons\n
"},{"location":"trulens_eval/api/huggingface_provider/#trulens_eval.trulens_eval.feedback.provider.hugs.Huggingface.positive_sentiment","title":"
positive_sentiment(text)","text":"
Uses Huggingface's cardiffnlp/twitter-roberta-base-sentiment model. A function that uses a sentiment classifier on text.
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback.provider.hugs import Huggingface\nhuggingface_provider = Huggingface()\n\nfeedback = Feedback(huggingface_provider.positive_sentiment).on_output() \n
The
on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str Text to evaluate.
required
Returns:
Name Type Description
float float A value between 0 and 1. 0 being \"negative sentiment\" and 1
float being \"positive sentiment\".
Source code in
trulens_eval/trulens_eval/feedback/provider/hugs.py @_tci\ndef positive_sentiment(self, text: str) -> float:\n \"\"\"\n Uses Huggingface's cardiffnlp/twitter-roberta-base-sentiment model. A\n function that uses a sentiment classifier on `text`.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.hugs import Huggingface\n huggingface_provider = Huggingface()\n\n feedback = Feedback(huggingface_provider.positive_sentiment).on_output() \n ```\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0 and 1. 0 being \"negative sentiment\" and 1\n being \"positive sentiment\".\n \"\"\"\n\n max_length = 500\n truncated_text = text[:max_length]\n payload = {\"inputs\": truncated_text}\n\n hf_response = self.endpoint.post(\n url=HUGS_SENTIMENT_API_URL, payload=payload\n )\n\n for label in hf_response:\n if label['label'] == 'LABEL_2':\n return float(label['score'])\n\n raise RuntimeError(\"LABEL_2 not found in huggingface api response.\")\n
"},{"location":"trulens_eval/api/litellm_provider/","title":"LiteLLM APIs","text":"
Below is how you can instantiate LiteLLM as a provider. LiteLLM supports 100+ models from OpenAI, Cohere, Anthropic, HuggingFace, Meta and more. You can find more information about models available here.
All feedback functions listed in the base LLMProvider class can be run with LiteLLM.
Bases: LLMProvider
Out of the box feedback functions calling LiteLLM API.
Source code in
trulens_eval/trulens_eval/feedback/provider/litellm.py class LiteLLM(LLMProvider):\n \"\"\"Out of the box feedback functions calling LiteLLM API.\n \"\"\"\n model_engine: str\n endpoint: Endpoint\n\n def __init__(\n self, *args, endpoint=None, model_engine=\"gpt-3.5-turbo\", **kwargs\n ):\n # NOTE(piotrm): pydantic adds endpoint to the signature of this\n # constructor if we don't include it explicitly, even though we set it\n # down below. Adding it as None here as a temporary hack.\n \"\"\"\n Create an LiteLLM Provider with out of the box feedback functions.\n\n **Usage:**\n ```\n from trulens_eval.feedback.provider.litellm import LiteLLM\n litellm_provider = LiteLLM()\n\n ```\n\n Args:\n model_engine (str): The LiteLLM completion model.Defaults to `gpt-3.5-turbo`\n endpoint (Endpoint): Internal Usage for DB serialization\n \"\"\"\n # TODO: why was self_kwargs required here independently of kwargs?\n self_kwargs = dict()\n self_kwargs.update(**kwargs)\n self_kwargs['model_engine'] = model_engine\n self_kwargs['endpoint'] = LiteLLMEndpoint(*args, **kwargs)\n\n super().__init__(\n **self_kwargs\n ) # need to include pydantic.BaseModel.__init__\n\n def _create_chat_completion(\n self,\n prompt: Optional[str] = None,\n messages: Optional[Sequence[Dict]] = None,\n **kwargs\n ) -> str:\n\n from litellm import completion\n if prompt is not None:\n comp = completion(\n model=self.model_engine,\n messages=[{\n \"role\": \"system\",\n \"content\": prompt\n }],\n **kwargs\n )\n elif messages is not None:\n comp = completion(\n model=self.model_engine, messages=messages, **kwargs\n )\n\n else:\n raise ValueError(\"`prompt` or `messages` must be specified.\")\n\n assert isinstance(comp, dict)\n\n return comp[\"choices\"][0][\"message\"][\"content\"]\n
"},{"location":"trulens_eval/api/litellm_provider/#trulens_eval.trulens_eval.feedback.provider.litellm.LiteLLM.__init__","title":"
__init__(*args, endpoint=None, model_engine='gpt-3.5-turbo', **kwargs)","text":"
Create an LiteLLM Provider with out of the box feedback functions.
Usage:
from trulens_eval.feedback.provider.litellm import LiteLLM\nlitellm_provider = LiteLLM()\n
Parameters:
Name Type Description Default
model_engine str The LiteLLM completion model.Defaults to gpt-3.5-turbo
'gpt-3.5-turbo' endpoint Endpoint Internal Usage for DB serialization
None Source code in
trulens_eval/trulens_eval/feedback/provider/litellm.py def __init__(\n self, *args, endpoint=None, model_engine=\"gpt-3.5-turbo\", **kwargs\n):\n # NOTE(piotrm): pydantic adds endpoint to the signature of this\n # constructor if we don't include it explicitly, even though we set it\n # down below. Adding it as None here as a temporary hack.\n \"\"\"\n Create an LiteLLM Provider with out of the box feedback functions.\n\n **Usage:**\n ```\n from trulens_eval.feedback.provider.litellm import LiteLLM\n litellm_provider = LiteLLM()\n\n ```\n\n Args:\n model_engine (str): The LiteLLM completion model.Defaults to `gpt-3.5-turbo`\n endpoint (Endpoint): Internal Usage for DB serialization\n \"\"\"\n # TODO: why was self_kwargs required here independently of kwargs?\n self_kwargs = dict()\n self_kwargs.update(**kwargs)\n self_kwargs['model_engine'] = model_engine\n self_kwargs['endpoint'] = LiteLLMEndpoint(*args, **kwargs)\n\n super().__init__(\n **self_kwargs\n ) # need to include pydantic.BaseModel.__init__\n
"},{"location":"trulens_eval/api/openai_provider/","title":"OpenAI APIs","text":"
Below is how you can instantiate OpenAI as a provider, along with feedback functions available only from OpenAI.
Additionally, all feedback functions listed in the base LLMProvider class can be run with OpenAI.
Bases: LLMProvider
Out of the box feedback functions calling OpenAI APIs.
Source code in
trulens_eval/trulens_eval/feedback/provider/openai.py class OpenAI(LLMProvider):\n \"\"\"Out of the box feedback functions calling OpenAI APIs.\n \"\"\"\n # model_engine: str # LLMProvider\n\n endpoint: Endpoint\n\n def __init__(\n self, *args, endpoint=None, model_engine=\"gpt-3.5-turbo\", **kwargs\n ):\n # NOTE(piotrm): pydantic adds endpoint to the signature of this\n # constructor if we don't include it explicitly, even though we set it\n # down below. Adding it as None here as a temporary hack.\n \"\"\"\n Create an OpenAI Provider with out of the box feedback functions.\n\n **Usage:**\n ```python\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n ```\n\n Args:\n model_engine (str): The OpenAI completion model. Defaults to\n `gpt-3.5-turbo`\n endpoint (Endpoint): Internal Usage for DB serialization\n \"\"\"\n # TODO: why was self_kwargs required here independently of kwargs?\n self_kwargs = dict()\n self_kwargs.update(**kwargs)\n self_kwargs['model_engine'] = model_engine\n self_kwargs['endpoint'] = OpenAIEndpoint(*args, **kwargs)\n\n super().__init__(\n **self_kwargs\n ) # need to include pydantic.BaseModel.__init__\n\n set_openai_key()\n\n # LLMProvider requirement\n def _create_chat_completion(\n self,\n prompt: Optional[str] = None,\n messages: Optional[Sequence[Dict]] = None,\n **kwargs\n ) -> str:\n\n if 'model' not in kwargs:\n kwargs['model'] = self.model_engine\n\n if 'temperature' not in kwargs:\n kwargs['temperature'] = 0.0\n\n if prompt is not None:\n comp = openai.ChatCompletion.create(\n messages=[{\n \"role\": \"system\",\n \"content\": prompt\n }], **kwargs\n )\n elif messages is not None:\n comp = openai.ChatCompletion.create(messages=messages, **kwargs)\n\n else:\n raise ValueError(\"`prompt` or `messages` must be specified.\")\n\n assert isinstance(comp, dict)\n\n return comp[\"choices\"][0][\"message\"][\"content\"]\n\n def _moderation(self, text: str):\n # See https://platform.openai.com/docs/guides/moderation/overview .\n return self.endpoint.run_me(\n lambda: openai.Moderation.create(input=text)\n )\n\n # TODEP\n def moderation_hate(self, text: str) -> float:\n \"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is hate\n speech.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_hate, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not hate) and 1.0 (hate).\n \"\"\"\n openai_response = self._moderation(text)\n return float(openai_response[\"results\"][0][\"category_scores\"][\"hate\"])\n\n # TODEP\n def moderation_hatethreatening(self, text: str) -> float:\n \"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is\n threatening speech.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_hatethreatening, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not threatening) and 1.0 (threatening).\n \"\"\"\n openai_response = self._moderation(text)\n\n return float(\n openai_response[\"results\"][0][\"category_scores\"][\"hate/threatening\"]\n )\n\n # TODEP\n def moderation_selfharm(self, text: str) -> float:\n \"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is about\n self harm.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_selfharm, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not self harm) and 1.0 (self harm).\n \"\"\"\n openai_response = self._moderation(text)\n\n return float(\n openai_response[\"results\"][0][\"category_scores\"][\"self-harm\"]\n )\n\n # TODEP\n def moderation_sexual(self, text: str) -> float:\n \"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is sexual\n speech.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_sexual, higher_is_better=False\n ).on_output()\n ```\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not sexual) and 1.0 (sexual).\n \"\"\"\n openai_response = self._moderation(text)\n\n return float(openai_response[\"results\"][0][\"category_scores\"][\"sexual\"])\n\n # TODEP\n def moderation_sexualminors(self, text: str) -> float:\n \"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is about\n sexual minors.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_sexualminors, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not sexual minors) and 1.0 (sexual\n minors).\n \"\"\"\n\n openai_response = self._moderation(text)\n\n return float(\n openai_response[\"results\"][0][\"category_scores\"][\"sexual/minors\"]\n )\n\n # TODEP\n def moderation_violence(self, text: str) -> float:\n \"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is about\n violence.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_violence, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not violence) and 1.0 (violence).\n \"\"\"\n openai_response = self._moderation(text)\n\n return float(\n openai_response[\"results\"][0][\"category_scores\"][\"violence\"]\n )\n\n # TODEP\n def moderation_violencegraphic(self, text: str) -> float:\n \"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is about\n graphic violence.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_violencegraphic, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (graphic violence) and 1.0 (not graphic\n violence).\n \"\"\"\n openai_response = self._moderation(text)\n\n return float(\n openai_response[\"results\"][0][\"category_scores\"][\"violence/graphic\"]\n )\n
"},{"location":"trulens_eval/api/openai_provider/#trulens_eval.trulens_eval.feedback.provider.openai.OpenAI.__init__","title":"
__init__(*args, endpoint=None, model_engine='gpt-3.5-turbo', **kwargs)","text":"
Create an OpenAI Provider with out of the box feedback functions.
Usage:
from trulens_eval.feedback.provider.openai import OpenAI\nopenai_provider = OpenAI()\n
Parameters:
Name Type Description Default
model_engine str The OpenAI completion model. Defaults to gpt-3.5-turbo
'gpt-3.5-turbo' endpoint Endpoint Internal Usage for DB serialization
None Source code in
trulens_eval/trulens_eval/feedback/provider/openai.py def __init__(\n self, *args, endpoint=None, model_engine=\"gpt-3.5-turbo\", **kwargs\n):\n # NOTE(piotrm): pydantic adds endpoint to the signature of this\n # constructor if we don't include it explicitly, even though we set it\n # down below. Adding it as None here as a temporary hack.\n \"\"\"\n Create an OpenAI Provider with out of the box feedback functions.\n\n **Usage:**\n ```python\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n ```\n\n Args:\n model_engine (str): The OpenAI completion model. Defaults to\n `gpt-3.5-turbo`\n endpoint (Endpoint): Internal Usage for DB serialization\n \"\"\"\n # TODO: why was self_kwargs required here independently of kwargs?\n self_kwargs = dict()\n self_kwargs.update(**kwargs)\n self_kwargs['model_engine'] = model_engine\n self_kwargs['endpoint'] = OpenAIEndpoint(*args, **kwargs)\n\n super().__init__(\n **self_kwargs\n ) # need to include pydantic.BaseModel.__init__\n\n set_openai_key()\n
"},{"location":"trulens_eval/api/openai_provider/#trulens_eval.trulens_eval.feedback.provider.openai.OpenAI.moderation_hate","title":"
moderation_hate(text)","text":"
Uses OpenAI's Moderation API. A function that checks if text is hate speech.
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback.provider.openai import OpenAI\nopenai_provider = OpenAI()\n\nfeedback = Feedback(\n openai_provider.moderation_hate, higher_is_better=False\n).on_output()\n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str Text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not hate) and 1.0 (hate).
Source code in
trulens_eval/trulens_eval/feedback/provider/openai.py def moderation_hate(self, text: str) -> float:\n \"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is hate\n speech.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_hate, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not hate) and 1.0 (hate).\n \"\"\"\n openai_response = self._moderation(text)\n return float(openai_response[\"results\"][0][\"category_scores\"][\"hate\"])\n
"},{"location":"trulens_eval/api/openai_provider/#trulens_eval.trulens_eval.feedback.provider.openai.OpenAI.moderation_hatethreatening","title":"
moderation_hatethreatening(text)","text":"
Uses OpenAI's Moderation API. A function that checks if text is threatening speech.
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback.provider.openai import OpenAI\nopenai_provider = OpenAI()\n\nfeedback = Feedback(\n openai_provider.moderation_hatethreatening, higher_is_better=False\n).on_output()\n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str Text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not threatening) and 1.0 (threatening).
Source code in
trulens_eval/trulens_eval/feedback/provider/openai.py def moderation_hatethreatening(self, text: str) -> float:\n \"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is\n threatening speech.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_hatethreatening, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not threatening) and 1.0 (threatening).\n \"\"\"\n openai_response = self._moderation(text)\n\n return float(\n openai_response[\"results\"][0][\"category_scores\"][\"hate/threatening\"]\n )\n
"},{"location":"trulens_eval/api/openai_provider/#trulens_eval.trulens_eval.feedback.provider.openai.OpenAI.moderation_selfharm","title":"
moderation_selfharm(text)","text":"
Uses OpenAI's Moderation API. A function that checks if text is about self harm.
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback.provider.openai import OpenAI\nopenai_provider = OpenAI()\n\nfeedback = Feedback(\n openai_provider.moderation_selfharm, higher_is_better=False\n).on_output()\n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str Text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not self harm) and 1.0 (self harm).
Source code in
trulens_eval/trulens_eval/feedback/provider/openai.py def moderation_selfharm(self, text: str) -> float:\n \"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is about\n self harm.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_selfharm, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not self harm) and 1.0 (self harm).\n \"\"\"\n openai_response = self._moderation(text)\n\n return float(\n openai_response[\"results\"][0][\"category_scores\"][\"self-harm\"]\n )\n
"},{"location":"trulens_eval/api/openai_provider/#trulens_eval.trulens_eval.feedback.provider.openai.OpenAI.moderation_sexual","title":"
moderation_sexual(text)","text":"
Uses OpenAI's Moderation API. A function that checks if text is sexual speech.
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback.provider.openai import OpenAI\nopenai_provider = OpenAI()\n\nfeedback = Feedback(\n openai_provider.moderation_sexual, higher_is_better=False\n).on_output()\n
The
on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str Text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not sexual) and 1.0 (sexual).
Source code in
trulens_eval/trulens_eval/feedback/provider/openai.py def moderation_sexual(self, text: str) -> float:\n \"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is sexual\n speech.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_sexual, higher_is_better=False\n ).on_output()\n ```\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not sexual) and 1.0 (sexual).\n \"\"\"\n openai_response = self._moderation(text)\n\n return float(openai_response[\"results\"][0][\"category_scores\"][\"sexual\"])\n
"},{"location":"trulens_eval/api/openai_provider/#trulens_eval.trulens_eval.feedback.provider.openai.OpenAI.moderation_sexualminors","title":"
moderation_sexualminors(text)","text":"
Uses OpenAI's Moderation API. A function that checks if text is about sexual minors.
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback.provider.openai import OpenAI\nopenai_provider = OpenAI()\n\nfeedback = Feedback(\n openai_provider.moderation_sexualminors, higher_is_better=False\n).on_output()\n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str Text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not sexual minors) and 1.0 (sexual
float minors).
Source code in
trulens_eval/trulens_eval/feedback/provider/openai.py def moderation_sexualminors(self, text: str) -> float:\n \"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is about\n sexual minors.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_sexualminors, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not sexual minors) and 1.0 (sexual\n minors).\n \"\"\"\n\n openai_response = self._moderation(text)\n\n return float(\n openai_response[\"results\"][0][\"category_scores\"][\"sexual/minors\"]\n )\n
"},{"location":"trulens_eval/api/openai_provider/#trulens_eval.trulens_eval.feedback.provider.openai.OpenAI.moderation_violence","title":"
moderation_violence(text)","text":"
Uses OpenAI's Moderation API. A function that checks if text is about violence.
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback.provider.openai import OpenAI\nopenai_provider = OpenAI()\n\nfeedback = Feedback(\n openai_provider.moderation_violence, higher_is_better=False\n).on_output()\n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str Text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not violence) and 1.0 (violence).
Source code in
trulens_eval/trulens_eval/feedback/provider/openai.py def moderation_violence(self, text: str) -> float:\n \"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is about\n violence.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_violence, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not violence) and 1.0 (violence).\n \"\"\"\n openai_response = self._moderation(text)\n\n return float(\n openai_response[\"results\"][0][\"category_scores\"][\"violence\"]\n )\n
"},{"location":"trulens_eval/api/openai_provider/#trulens_eval.trulens_eval.feedback.provider.openai.OpenAI.moderation_violencegraphic","title":"
moderation_violencegraphic(text)","text":"
Uses OpenAI's Moderation API. A function that checks if text is about graphic violence.
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback.provider.openai import OpenAI\nopenai_provider = OpenAI()\n\nfeedback = Feedback(\n openai_provider.moderation_violencegraphic, higher_is_better=False\n).on_output()\n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str Text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (graphic violence) and 1.0 (not graphic
float violence).
Source code in
trulens_eval/trulens_eval/feedback/provider/openai.py def moderation_violencegraphic(self, text: str) -> float:\n \"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is about\n graphic violence.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_violencegraphic, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (graphic violence) and 1.0 (not graphic\n violence).\n \"\"\"\n openai_response = self._moderation(text)\n\n return float(\n openai_response[\"results\"][0][\"category_scores\"][\"violence/graphic\"]\n )\n
"},{"location":"trulens_eval/api/tru/","title":"Tru","text":"
Bases: SingletonPerName
Tru is the main class that provides an entry points to trulens-eval. Tru lets you:
- Log app prompts and outputs
- Log app Metadata
- Run and log feedback functions
- Run streamlit dashboard to view experiment results
By default, all data is logged to the current working directory to default.sqlite. Data can be logged to a SQLAlchemy-compatible referred to by database_url.
Source code in
trulens_eval/trulens_eval/tru.py class Tru(SingletonPerName):\n \"\"\"\n Tru is the main class that provides an entry points to trulens-eval. Tru lets you:\n\n * Log app prompts and outputs\n * Log app Metadata\n * Run and log feedback functions\n * Run streamlit dashboard to view experiment results\n\n By default, all data is logged to the current working directory to `default.sqlite`. \n Data can be logged to a SQLAlchemy-compatible referred to by `database_url`.\n \"\"\"\n DEFAULT_DATABASE_FILE = \"default.sqlite\"\n\n # Process or Thread of the deferred feedback function evaluator.\n evaluator_proc = None\n\n # Process of the dashboard app.\n dashboard_proc = None\n\n def Chain(self, chain, **kwargs):\n \"\"\"\n Create a TruChain with database managed by self.\n \"\"\"\n\n from trulens_eval.tru_chain import TruChain\n\n return TruChain(tru=self, app=chain, **kwargs)\n\n def Llama(self, engine, **kwargs):\n \"\"\"\n Create a llama_index engine with database managed by self.\n \"\"\"\n\n from trulens_eval.tru_llama import TruLlama\n\n return TruLlama(tru=self, app=engine, **kwargs)\n\n def Basic(self, text_to_text, **kwargs):\n from trulens_eval.tru_basic_app import TruBasicApp\n\n return TruBasicApp(tru=self, text_to_text=text_to_text, **kwargs)\n\n def Custom(self, app, **kwargs):\n from trulens_eval.tru_custom_app import TruCustomApp\n\n return TruCustomApp(tru=self, app=app, **kwargs)\n\n def __init__(\n self,\n database_url: Optional[str] = None,\n database_file: Optional[str] = None,\n database_redact_keys: bool = False\n ):\n \"\"\"\n TruLens instrumentation, logging, and feedback functions for apps.\n\n Args:\n database_url: SQLAlchemy database URL. Defaults to a local\n SQLite database file at 'default.sqlite'\n See [this article](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls)\n on SQLAlchemy database URLs.\n database_file: (Deprecated) Path to a local SQLite database file\n database_redact_keys: whether to redact secret keys in data to be written to database.\n \"\"\"\n if hasattr(self, \"db\"):\n if database_url is not None or database_file is not None:\n logger.warning(\n f\"Tru was already initialized. Cannot change database_url={database_url} or database_file={database_file} .\"\n )\n\n # Already initialized by SingletonByName mechanism.\n return\n\n assert None in (database_url, database_file), \\\n \"Please specify at most one of `database_url` and `database_file`\"\n\n if database_file:\n warnings.warn(\n \"`database_file` is deprecated, use `database_url` instead as in `database_url='sqlite:///filename'.\",\n DeprecationWarning,\n stacklevel=2\n )\n\n if database_url is None:\n database_url = f\"sqlite:///{database_file or self.DEFAULT_DATABASE_FILE}\"\n\n self.db: SqlAlchemyDB = SqlAlchemyDB.from_db_url(\n database_url, redact_keys=database_redact_keys\n )\n\n print(\n f\"{UNICODE_SQUID} Tru initialized with db url {self.db.engine.url} .\"\n )\n if database_redact_keys:\n print(\n f\"{UNICODE_LOCK} Secret keys will not be included in the database.\"\n )\n else:\n print(\n f\"{UNICODE_STOP} Secret keys may be written to the database. \"\n \"See the `database_redact_keys` option of `Tru` to prevent this.\"\n )\n\n def reset_database(self):\n \"\"\"\n Reset the database. Clears all tables.\n \"\"\"\n\n self.db.reset_database()\n\n def migrate_database(self):\n \"\"\"\n Migrates the database. This should be run whenever there are breaking\n changes in a database created with an older version of trulens_eval.\n \"\"\"\n\n self.db.migrate_database()\n\n def add_record(self, record: Optional[Record] = None, **kwargs):\n \"\"\"\n Add a record to the database.\n\n Args:\n\n record: Record\n\n **kwargs: Record fields.\n\n Returns:\n RecordID: Unique record identifier.\n\n \"\"\"\n\n if record is None:\n record = Record(**kwargs)\n else:\n record.update(**kwargs)\n\n return self.db.insert_record(record=record)\n\n update_record = add_record\n\n def _submit_feedback_functions(\n self,\n record: Record,\n feedback_functions: Sequence[Feedback],\n app: Optional[AppDefinition] = None,\n on_done: Optional[Callable[['Future[Tuple[Feedback,FeedbackResult]]'],\n None]] = None\n ) -> List['Future[Tuple[Feedback,FeedbackResult]]']:\n app_id = record.app_id\n\n self.db: DB\n\n if app is None:\n app = AppDefinition.parse_obj(self.db.get_app(app_id=app_id))\n if app is None:\n raise RuntimeError(\n \"App {app_id} not present in db. \"\n \"Either add it with `tru.add_app` or provide `app_json` to `tru.run_feedback_functions`.\"\n )\n\n else:\n assert app_id == app.app_id, \"Record was produced by a different app.\"\n\n if self.db.get_app(app_id=app.app_id) is None:\n logger.warning(\n \"App {app_id} was not present in database. Adding it.\"\n )\n self.add_app(app=app)\n\n futures = []\n\n tp: TP = TP()\n\n for ffunc in feedback_functions:\n fut: 'Future[Tuple[Feedback,FeedbackResult]]' = \\\n tp.submit(lambda f: (f, f.run(app=app, record=record)), ffunc)\n\n if on_done is not None:\n fut.add_done_callback(on_done)\n\n futures.append(fut)\n\n return futures\n\n def run_feedback_functions(\n self,\n record: Record,\n feedback_functions: Sequence[Feedback],\n app: Optional[AppDefinition] = None,\n ) -> Iterable[FeedbackResult]:\n \"\"\"\n Run a collection of feedback functions and report their result.\n\n Parameters:\n\n record (Record): The record on which to evaluate the feedback\n functions.\n\n app (App, optional): The app that produced the given record.\n If not provided, it is looked up from the given database `db`.\n\n feedback_functions (Sequence[Feedback]): A collection of feedback\n functions to evaluate.\n\n Yields `FeedbackResult`, one for each element of `feedback_functions`\n potentially in random order.\n \"\"\"\n\n for res in as_completed(self._submit_feedback_functions(\n record=record, feedback_functions=feedback_functions, app=app)):\n\n yield res.result()[1]\n\n def add_app(self, app: AppDefinition) -> None:\n \"\"\"\n Add a app to the database. \n \"\"\"\n\n self.db.insert_app(app=app)\n\n def add_feedback(\n self, feedback_result: FeedbackResult = None, **kwargs\n ) -> None:\n \"\"\"\n Add a single feedback result to the database.\n \"\"\"\n\n if feedback_result is None:\n feedback_result = FeedbackResult(**kwargs)\n else:\n feedback_result.update(**kwargs)\n\n self.db.insert_feedback(feedback_result=feedback_result)\n\n def add_feedbacks(self, feedback_results: Iterable[FeedbackResult]) -> None:\n \"\"\"\n Add multiple feedback results to the database.\n \"\"\"\n\n for feedback_result in feedback_results:\n self.add_feedback(feedback_result=feedback_result)\n\n def get_app(self, app_id: Optional[str] = None) -> JSON:\n \"\"\"\n Look up a app from the database.\n \"\"\"\n\n return self.db.get_app(app_id)\n\n def get_apps(self) -> Iterable[JSON]:\n \"\"\"\n Look up all apps from the database.\n \"\"\"\n\n return self.db.get_apps()\n\n def get_records_and_feedback(self, app_ids: List[str]):\n \"\"\"\n Get records, their feeback results, and feedback names from the\n database. Pass an empty list of app_ids to return all.\n\n ```python\n tru.get_records_and_feedback(app_ids=[])\n ```\n \"\"\"\n\n df, feedback_columns = self.db.get_records_and_feedback(app_ids)\n\n return df, feedback_columns\n\n def get_leaderboard(self, app_ids: List[str]):\n \"\"\"\n Get a leaderboard by app id from the\n database. Pass an empty list of app_ids to return all.\n\n ```python\n tru.get_leaderboard(app_ids=[])\n ```\n \"\"\"\n df, feedback_cols = self.db.get_records_and_feedback(app_ids)\n\n col_agg_list = feedback_cols + ['latency', 'total_cost']\n\n leaderboard = df.groupby('app_id')[col_agg_list].mean().sort_values(\n by=feedback_cols, ascending=False\n )\n\n return leaderboard\n\n def start_evaluator(self,\n restart=False,\n fork=False) -> Union[Process, Thread]:\n \"\"\"\n Start a deferred feedback function evaluation thread.\n \"\"\"\n\n assert not fork, \"Fork mode not yet implemented.\"\n\n if self.evaluator_proc is not None:\n if restart:\n self.stop_evaluator()\n else:\n raise RuntimeError(\n \"Evaluator is already running in this process.\"\n )\n\n if not fork:\n self.evaluator_stop = threading.Event()\n\n def runloop():\n assert self.evaluator_stop is not None\n\n while fork or not self.evaluator_stop.is_set():\n futures = Feedback.evaluate_deferred(tru=self)\n\n if len(futures) > 0:\n print(\n f\"{UNICODE_YIELD}{UNICODE_YIELD}{UNICODE_YIELD} Started {len(futures)} deferred feedback functions.\"\n )\n wait(futures)\n print(\n f\"{UNICODE_CHECK}{UNICODE_CHECK}{UNICODE_CHECK} Finished evaluating deferred feedback functions.\"\n )\n\n if fork:\n sleep(10)\n else:\n self.evaluator_stop.wait(10)\n\n print(\"Evaluator stopped.\")\n\n if fork:\n proc = Process(target=runloop)\n else:\n proc = Thread(target=runloop)\n proc.daemon = True\n\n # Start a persistent thread or process that evaluates feedback functions.\n\n self.evaluator_proc = proc\n proc.start()\n\n return proc\n\n def stop_evaluator(self):\n \"\"\"\n Stop the deferred feedback evaluation thread.\n \"\"\"\n\n if self.evaluator_proc is None:\n raise RuntimeError(\"Evaluator not running this process.\")\n\n if isinstance(self.evaluator_proc, Process):\n self.evaluator_proc.terminate()\n\n elif isinstance(self.evaluator_proc, Thread):\n self.evaluator_stop.set()\n self.evaluator_proc.join()\n self.evaluator_stop = None\n\n self.evaluator_proc = None\n\n def stop_dashboard(self, force: bool = False) -> None:\n \"\"\"\n Stop existing dashboard(s) if running.\n\n Args:\n\n - force: bool: Also try to find any other dashboard processes not\n started in this notebook and shut them down too.\n\n Raises:\n\n - ValueError: Dashboard is not running.\n \"\"\"\n if Tru.dashboard_proc is None:\n if not force:\n raise ValueError(\n \"Dashboard not running in this workspace. \"\n \"You may be able to shut other instances by setting the `force` flag.\"\n )\n\n else:\n if sys.platform.startswith(\"win\"):\n raise RuntimeError(\n \"Force stop option is not supported on windows.\"\n )\n\n print(\"Force stopping dashboard ...\")\n import os\n import pwd # PROBLEM: does not exist on windows\n\n import psutil\n username = pwd.getpwuid(os.getuid())[0]\n for p in psutil.process_iter():\n try:\n cmd = \" \".join(p.cmdline())\n if \"streamlit\" in cmd and \"Leaderboard.py\" in cmd and p.username(\n ) == username:\n print(f\"killing {p}\")\n p.kill()\n except Exception as e:\n continue\n\n else:\n Tru.dashboard_proc.kill()\n Tru.dashboard_proc = None\n\n def run_dashboard_in_jupyter(self):\n \"\"\"\n Experimental approach to attempt to display the dashboard inside a\n jupyter notebook. Relies on the `streamlit_jupyter` package.\n \"\"\"\n # EXPERIMENTAL\n # TODO: check for jupyter\n\n logger.warning(\n \"Running dashboard inside a notebook is an experimental feature and may not work well.\"\n )\n\n from streamlit_jupyter import StreamlitPatcher\n StreamlitPatcher().jupyter()\n from trulens_eval import Leaderboard\n\n Leaderboard.main()\n\n def run_dashboard(\n self, force: bool = False, _dev: Optional[Path] = None\n ) -> Process:\n \"\"\"\n Run a streamlit dashboard to view logged results and apps.\n\n Args:\n\n - force: bool: Stop existing dashboard(s) first.\n\n - _dev: Optional[Path]: If given, run dashboard with the given\n PYTHONPATH. This can be used to run the dashboard from outside of\n its pip package installation folder.\n\n Raises:\n\n - ValueError: Dashboard is already running.\n\n Returns:\n\n - Process: Process containing streamlit dashboard.\n \"\"\"\n\n if force:\n self.stop_dashboard(force=force)\n\n print(\"Starting dashboard ...\")\n\n # Create .streamlit directory if it doesn't exist\n streamlit_dir = os.path.join(os.getcwd(), '.streamlit')\n os.makedirs(streamlit_dir, exist_ok=True)\n\n # Create config.toml file path\n config_path = os.path.join(streamlit_dir, 'config.toml')\n\n # Check if the file already exists\n if not os.path.exists(config_path):\n with open(config_path, 'w') as f:\n f.write('[theme]\\n')\n f.write('primaryColor=\"#0A2C37\"\\n')\n f.write('backgroundColor=\"#FFFFFF\"\\n')\n f.write('secondaryBackgroundColor=\"F5F5F5\"\\n')\n f.write('textColor=\"#0A2C37\"\\n')\n f.write('font=\"sans serif\"\\n')\n else:\n print(\"Config file already exists. Skipping writing process.\")\n\n # Create credentials.toml file path\n cred_path = os.path.join(streamlit_dir, 'credentials.toml')\n\n # Check if the file already exists\n if not os.path.exists(cred_path):\n with open(cred_path, 'w') as f:\n f.write('[general]\\n')\n f.write('email=\"\"\\n')\n else:\n print(\"Credentials file already exists. Skipping writing process.\")\n\n #run leaderboard with subprocess\n leaderboard_path = pkg_resources.resource_filename(\n 'trulens_eval', 'Leaderboard.py'\n )\n\n if Tru.dashboard_proc is not None:\n print(\"Dashboard already running at path:\", Tru.dashboard_urls)\n return Tru.dashboard_proc\n\n env_opts = {}\n if _dev is not None:\n env_opts['env'] = os.environ\n env_opts['env']['PYTHONPATH'] = str(_dev)\n\n proc = subprocess.Popen(\n [\n \"streamlit\", \"run\", \"--server.headless=True\", leaderboard_path,\n \"--\", \"--database-url\",\n self.db.engine.url.render_as_string(hide_password=False)\n ],\n stdout=subprocess.PIPE,\n stderr=subprocess.PIPE,\n text=True,\n **env_opts\n )\n\n started = threading.Event()\n tunnel_started = threading.Event()\n if is_notebook():\n out_stdout, out_stderr = setup_widget_stdout_stderr()\n else:\n out_stdout = None\n out_stderr = None\n\n IN_COLAB = 'google.colab' in sys.modules\n if IN_COLAB:\n tunnel_proc = subprocess.Popen(\n [\"npx\", \"localtunnel\", \"--port\", \"8501\"],\n stdout=subprocess.PIPE,\n stderr=subprocess.PIPE,\n text=True,\n **env_opts\n )\n\n def listen_to_tunnel(proc: subprocess.Popen, pipe, out, started):\n while proc.poll() is None:\n\n line = pipe.readline()\n if \"url\" in line:\n started.set()\n line = \"Go to this url and submit the ip given here. \" + line\n\n if out is not None:\n out.append_stdout(line)\n\n else:\n print(line)\n\n Tru.tunnel_listener_stdout = Thread(\n target=listen_to_tunnel,\n args=(\n tunnel_proc, tunnel_proc.stdout, out_stdout, tunnel_started\n )\n )\n Tru.tunnel_listener_stderr = Thread(\n target=listen_to_tunnel,\n args=(\n tunnel_proc, tunnel_proc.stderr, out_stderr, tunnel_started\n )\n )\n Tru.tunnel_listener_stdout.daemon = True\n Tru.tunnel_listener_stderr.daemon = True\n Tru.tunnel_listener_stdout.start()\n Tru.tunnel_listener_stderr.start()\n if not tunnel_started.wait(timeout=DASHBOARD_START_TIMEOUT\n ): # This might not work on windows.\n raise RuntimeError(\"Tunnel failed to start in time. \")\n\n def listen_to_dashboard(proc: subprocess.Popen, pipe, out, started):\n while proc.poll() is None:\n line = pipe.readline()\n if IN_COLAB:\n if \"External URL: \" in line:\n started.set()\n line = line.replace(\n \"External URL: http://\", \"Submit this IP Address: \"\n )\n line = line.replace(\":8501\", \"\")\n if out is not None:\n out.append_stdout(line)\n else:\n print(line)\n Tru.dashboard_urls = line # store the url when dashboard is started\n else:\n if \"Network URL: \" in line:\n url = line.split(\": \")[1]\n url = url.rstrip()\n print(f\"Dashboard started at {url} .\")\n started.set()\n Tru.dashboard_urls = line # store the url when dashboard is started\n if out is not None:\n out.append_stdout(line)\n else:\n print(line)\n if out is not None:\n out.append_stdout(\"Dashboard closed.\")\n else:\n print(\"Dashboard closed.\")\n\n Tru.dashboard_listener_stdout = Thread(\n target=listen_to_dashboard,\n args=(proc, proc.stdout, out_stdout, started)\n )\n Tru.dashboard_listener_stderr = Thread(\n target=listen_to_dashboard,\n args=(proc, proc.stderr, out_stderr, started)\n )\n\n # Purposely block main process from ending and wait for dashboard.\n Tru.dashboard_listener_stdout.daemon = False\n Tru.dashboard_listener_stderr.daemon = False\n\n Tru.dashboard_listener_stdout.start()\n Tru.dashboard_listener_stderr.start()\n\n Tru.dashboard_proc = proc\n\n wait_period = DASHBOARD_START_TIMEOUT\n if IN_COLAB:\n # Need more time to setup 2 processes tunnel and dashboard\n wait_period = wait_period * 3\n if not started.wait(timeout=wait_period\n ): # This might not work on windows.\n raise RuntimeError(\n \"Dashboard failed to start in time. \"\n \"Please inspect dashboard logs for additional information.\"\n )\n\n return proc\n\n start_dashboard = run_dashboard\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.Chain","title":"
Chain(chain, **kwargs)","text":"
Create a TruChain with database managed by self.
Source code in
trulens_eval/trulens_eval/tru.py def Chain(self, chain, **kwargs):\n \"\"\"\n Create a TruChain with database managed by self.\n \"\"\"\n\n from trulens_eval.tru_chain import TruChain\n\n return TruChain(tru=self, app=chain, **kwargs)\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.Llama","title":"
Llama(engine, **kwargs)","text":"
Create a llama_index engine with database managed by self.
Source code in
trulens_eval/trulens_eval/tru.py def Llama(self, engine, **kwargs):\n \"\"\"\n Create a llama_index engine with database managed by self.\n \"\"\"\n\n from trulens_eval.tru_llama import TruLlama\n\n return TruLlama(tru=self, app=engine, **kwargs)\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.__init__","title":"
__init__(database_url=None, database_file=None, database_redact_keys=False)","text":"
TruLens instrumentation, logging, and feedback functions for apps.
Parameters:
Name Type Description Default
database_url Optional[str] SQLAlchemy database URL. Defaults to a local SQLite database file at 'default.sqlite' See this article on SQLAlchemy database URLs.
None database_file Optional[str] (Deprecated) Path to a local SQLite database file
None database_redact_keys bool whether to redact secret keys in data to be written to database.
False Source code in
trulens_eval/trulens_eval/tru.py def __init__(\n self,\n database_url: Optional[str] = None,\n database_file: Optional[str] = None,\n database_redact_keys: bool = False\n):\n \"\"\"\n TruLens instrumentation, logging, and feedback functions for apps.\n\n Args:\n database_url: SQLAlchemy database URL. Defaults to a local\n SQLite database file at 'default.sqlite'\n See [this article](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls)\n on SQLAlchemy database URLs.\n database_file: (Deprecated) Path to a local SQLite database file\n database_redact_keys: whether to redact secret keys in data to be written to database.\n \"\"\"\n if hasattr(self, \"db\"):\n if database_url is not None or database_file is not None:\n logger.warning(\n f\"Tru was already initialized. Cannot change database_url={database_url} or database_file={database_file} .\"\n )\n\n # Already initialized by SingletonByName mechanism.\n return\n\n assert None in (database_url, database_file), \\\n \"Please specify at most one of `database_url` and `database_file`\"\n\n if database_file:\n warnings.warn(\n \"`database_file` is deprecated, use `database_url` instead as in `database_url='sqlite:///filename'.\",\n DeprecationWarning,\n stacklevel=2\n )\n\n if database_url is None:\n database_url = f\"sqlite:///{database_file or self.DEFAULT_DATABASE_FILE}\"\n\n self.db: SqlAlchemyDB = SqlAlchemyDB.from_db_url(\n database_url, redact_keys=database_redact_keys\n )\n\n print(\n f\"{UNICODE_SQUID} Tru initialized with db url {self.db.engine.url} .\"\n )\n if database_redact_keys:\n print(\n f\"{UNICODE_LOCK} Secret keys will not be included in the database.\"\n )\n else:\n print(\n f\"{UNICODE_STOP} Secret keys may be written to the database. \"\n \"See the `database_redact_keys` option of `Tru` to prevent this.\"\n )\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.add_app","title":"
add_app(app)","text":"
Add a app to the database.
Source code in
trulens_eval/trulens_eval/tru.py def add_app(self, app: AppDefinition) -> None:\n \"\"\"\n Add a app to the database. \n \"\"\"\n\n self.db.insert_app(app=app)\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.add_feedback","title":"
add_feedback(feedback_result=None, **kwargs)","text":"
Add a single feedback result to the database.
Source code in
trulens_eval/trulens_eval/tru.py def add_feedback(\n self, feedback_result: FeedbackResult = None, **kwargs\n) -> None:\n \"\"\"\n Add a single feedback result to the database.\n \"\"\"\n\n if feedback_result is None:\n feedback_result = FeedbackResult(**kwargs)\n else:\n feedback_result.update(**kwargs)\n\n self.db.insert_feedback(feedback_result=feedback_result)\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.add_feedbacks","title":"
add_feedbacks(feedback_results)","text":"
Add multiple feedback results to the database.
Source code in
trulens_eval/trulens_eval/tru.py def add_feedbacks(self, feedback_results: Iterable[FeedbackResult]) -> None:\n \"\"\"\n Add multiple feedback results to the database.\n \"\"\"\n\n for feedback_result in feedback_results:\n self.add_feedback(feedback_result=feedback_result)\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.add_record","title":"
add_record(record=None, **kwargs)","text":"
Add a record to the database.
Args:
record: Record\n\n**kwargs: Record fields.\n
Returns:
Name Type Description
RecordID Unique record identifier.
Source code in
trulens_eval/trulens_eval/tru.py def add_record(self, record: Optional[Record] = None, **kwargs):\n \"\"\"\n Add a record to the database.\n\n Args:\n\n record: Record\n\n **kwargs: Record fields.\n\n Returns:\n RecordID: Unique record identifier.\n\n \"\"\"\n\n if record is None:\n record = Record(**kwargs)\n else:\n record.update(**kwargs)\n\n return self.db.insert_record(record=record)\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.get_app","title":"
get_app(app_id=None)","text":"
Look up a app from the database.
Source code in
trulens_eval/trulens_eval/tru.py def get_app(self, app_id: Optional[str] = None) -> JSON:\n \"\"\"\n Look up a app from the database.\n \"\"\"\n\n return self.db.get_app(app_id)\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.get_apps","title":"
get_apps()","text":"
Look up all apps from the database.
Source code in
trulens_eval/trulens_eval/tru.py def get_apps(self) -> Iterable[JSON]:\n \"\"\"\n Look up all apps from the database.\n \"\"\"\n\n return self.db.get_apps()\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.get_leaderboard","title":"
get_leaderboard(app_ids)","text":"
Get a leaderboard by app id from the database. Pass an empty list of app_ids to return all.
tru.get_leaderboard(app_ids=[])\n
Source code in
trulens_eval/trulens_eval/tru.py def get_leaderboard(self, app_ids: List[str]):\n \"\"\"\n Get a leaderboard by app id from the\n database. Pass an empty list of app_ids to return all.\n\n ```python\n tru.get_leaderboard(app_ids=[])\n ```\n \"\"\"\n df, feedback_cols = self.db.get_records_and_feedback(app_ids)\n\n col_agg_list = feedback_cols + ['latency', 'total_cost']\n\n leaderboard = df.groupby('app_id')[col_agg_list].mean().sort_values(\n by=feedback_cols, ascending=False\n )\n\n return leaderboard\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.get_records_and_feedback","title":"
get_records_and_feedback(app_ids)","text":"
Get records, their feeback results, and feedback names from the database. Pass an empty list of app_ids to return all.
tru.get_records_and_feedback(app_ids=[])\n
Source code in
trulens_eval/trulens_eval/tru.py def get_records_and_feedback(self, app_ids: List[str]):\n \"\"\"\n Get records, their feeback results, and feedback names from the\n database. Pass an empty list of app_ids to return all.\n\n ```python\n tru.get_records_and_feedback(app_ids=[])\n ```\n \"\"\"\n\n df, feedback_columns = self.db.get_records_and_feedback(app_ids)\n\n return df, feedback_columns\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.migrate_database","title":"
migrate_database()","text":"
Migrates the database. This should be run whenever there are breaking changes in a database created with an older version of trulens_eval.
Source code in
trulens_eval/trulens_eval/tru.py def migrate_database(self):\n \"\"\"\n Migrates the database. This should be run whenever there are breaking\n changes in a database created with an older version of trulens_eval.\n \"\"\"\n\n self.db.migrate_database()\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.reset_database","title":"
reset_database()","text":"
Reset the database. Clears all tables.
Source code in
trulens_eval/trulens_eval/tru.py def reset_database(self):\n \"\"\"\n Reset the database. Clears all tables.\n \"\"\"\n\n self.db.reset_database()\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.run_dashboard","title":"
run_dashboard(force=False, _dev=None)","text":"
Run a streamlit dashboard to view logged results and apps.
Args:
- force: bool: Stop existing dashboard(s) first.\n\n- _dev: Optional[Path]: If given, run dashboard with the given\n PYTHONPATH. This can be used to run the dashboard from outside of\n its pip package installation folder.\n
Raises:
- ValueError: Dashboard is already running.\n
Returns:
- Process: Process containing streamlit dashboard.\n
Source code in
trulens_eval/trulens_eval/tru.py def run_dashboard(\n self, force: bool = False, _dev: Optional[Path] = None\n) -> Process:\n \"\"\"\n Run a streamlit dashboard to view logged results and apps.\n\n Args:\n\n - force: bool: Stop existing dashboard(s) first.\n\n - _dev: Optional[Path]: If given, run dashboard with the given\n PYTHONPATH. This can be used to run the dashboard from outside of\n its pip package installation folder.\n\n Raises:\n\n - ValueError: Dashboard is already running.\n\n Returns:\n\n - Process: Process containing streamlit dashboard.\n \"\"\"\n\n if force:\n self.stop_dashboard(force=force)\n\n print(\"Starting dashboard ...\")\n\n # Create .streamlit directory if it doesn't exist\n streamlit_dir = os.path.join(os.getcwd(), '.streamlit')\n os.makedirs(streamlit_dir, exist_ok=True)\n\n # Create config.toml file path\n config_path = os.path.join(streamlit_dir, 'config.toml')\n\n # Check if the file already exists\n if not os.path.exists(config_path):\n with open(config_path, 'w') as f:\n f.write('[theme]\\n')\n f.write('primaryColor=\"#0A2C37\"\\n')\n f.write('backgroundColor=\"#FFFFFF\"\\n')\n f.write('secondaryBackgroundColor=\"F5F5F5\"\\n')\n f.write('textColor=\"#0A2C37\"\\n')\n f.write('font=\"sans serif\"\\n')\n else:\n print(\"Config file already exists. Skipping writing process.\")\n\n # Create credentials.toml file path\n cred_path = os.path.join(streamlit_dir, 'credentials.toml')\n\n # Check if the file already exists\n if not os.path.exists(cred_path):\n with open(cred_path, 'w') as f:\n f.write('[general]\\n')\n f.write('email=\"\"\\n')\n else:\n print(\"Credentials file already exists. Skipping writing process.\")\n\n #run leaderboard with subprocess\n leaderboard_path = pkg_resources.resource_filename(\n 'trulens_eval', 'Leaderboard.py'\n )\n\n if Tru.dashboard_proc is not None:\n print(\"Dashboard already running at path:\", Tru.dashboard_urls)\n return Tru.dashboard_proc\n\n env_opts = {}\n if _dev is not None:\n env_opts['env'] = os.environ\n env_opts['env']['PYTHONPATH'] = str(_dev)\n\n proc = subprocess.Popen(\n [\n \"streamlit\", \"run\", \"--server.headless=True\", leaderboard_path,\n \"--\", \"--database-url\",\n self.db.engine.url.render_as_string(hide_password=False)\n ],\n stdout=subprocess.PIPE,\n stderr=subprocess.PIPE,\n text=True,\n **env_opts\n )\n\n started = threading.Event()\n tunnel_started = threading.Event()\n if is_notebook():\n out_stdout, out_stderr = setup_widget_stdout_stderr()\n else:\n out_stdout = None\n out_stderr = None\n\n IN_COLAB = 'google.colab' in sys.modules\n if IN_COLAB:\n tunnel_proc = subprocess.Popen(\n [\"npx\", \"localtunnel\", \"--port\", \"8501\"],\n stdout=subprocess.PIPE,\n stderr=subprocess.PIPE,\n text=True,\n **env_opts\n )\n\n def listen_to_tunnel(proc: subprocess.Popen, pipe, out, started):\n while proc.poll() is None:\n\n line = pipe.readline()\n if \"url\" in line:\n started.set()\n line = \"Go to this url and submit the ip given here. \" + line\n\n if out is not None:\n out.append_stdout(line)\n\n else:\n print(line)\n\n Tru.tunnel_listener_stdout = Thread(\n target=listen_to_tunnel,\n args=(\n tunnel_proc, tunnel_proc.stdout, out_stdout, tunnel_started\n )\n )\n Tru.tunnel_listener_stderr = Thread(\n target=listen_to_tunnel,\n args=(\n tunnel_proc, tunnel_proc.stderr, out_stderr, tunnel_started\n )\n )\n Tru.tunnel_listener_stdout.daemon = True\n Tru.tunnel_listener_stderr.daemon = True\n Tru.tunnel_listener_stdout.start()\n Tru.tunnel_listener_stderr.start()\n if not tunnel_started.wait(timeout=DASHBOARD_START_TIMEOUT\n ): # This might not work on windows.\n raise RuntimeError(\"Tunnel failed to start in time. \")\n\n def listen_to_dashboard(proc: subprocess.Popen, pipe, out, started):\n while proc.poll() is None:\n line = pipe.readline()\n if IN_COLAB:\n if \"External URL: \" in line:\n started.set()\n line = line.replace(\n \"External URL: http://\", \"Submit this IP Address: \"\n )\n line = line.replace(\":8501\", \"\")\n if out is not None:\n out.append_stdout(line)\n else:\n print(line)\n Tru.dashboard_urls = line # store the url when dashboard is started\n else:\n if \"Network URL: \" in line:\n url = line.split(\": \")[1]\n url = url.rstrip()\n print(f\"Dashboard started at {url} .\")\n started.set()\n Tru.dashboard_urls = line # store the url when dashboard is started\n if out is not None:\n out.append_stdout(line)\n else:\n print(line)\n if out is not None:\n out.append_stdout(\"Dashboard closed.\")\n else:\n print(\"Dashboard closed.\")\n\n Tru.dashboard_listener_stdout = Thread(\n target=listen_to_dashboard,\n args=(proc, proc.stdout, out_stdout, started)\n )\n Tru.dashboard_listener_stderr = Thread(\n target=listen_to_dashboard,\n args=(proc, proc.stderr, out_stderr, started)\n )\n\n # Purposely block main process from ending and wait for dashboard.\n Tru.dashboard_listener_stdout.daemon = False\n Tru.dashboard_listener_stderr.daemon = False\n\n Tru.dashboard_listener_stdout.start()\n Tru.dashboard_listener_stderr.start()\n\n Tru.dashboard_proc = proc\n\n wait_period = DASHBOARD_START_TIMEOUT\n if IN_COLAB:\n # Need more time to setup 2 processes tunnel and dashboard\n wait_period = wait_period * 3\n if not started.wait(timeout=wait_period\n ): # This might not work on windows.\n raise RuntimeError(\n \"Dashboard failed to start in time. \"\n \"Please inspect dashboard logs for additional information.\"\n )\n\n return proc\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.run_dashboard_in_jupyter","title":"
run_dashboard_in_jupyter()","text":"
Experimental approach to attempt to display the dashboard inside a jupyter notebook. Relies on the streamlit_jupyter package.
Source code in
trulens_eval/trulens_eval/tru.py def run_dashboard_in_jupyter(self):\n \"\"\"\n Experimental approach to attempt to display the dashboard inside a\n jupyter notebook. Relies on the `streamlit_jupyter` package.\n \"\"\"\n # EXPERIMENTAL\n # TODO: check for jupyter\n\n logger.warning(\n \"Running dashboard inside a notebook is an experimental feature and may not work well.\"\n )\n\n from streamlit_jupyter import StreamlitPatcher\n StreamlitPatcher().jupyter()\n from trulens_eval import Leaderboard\n\n Leaderboard.main()\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.run_feedback_functions","title":"
run_feedback_functions(record, feedback_functions, app=None)","text":"
Run a collection of feedback functions and report their result.
Parameters:
record (Record): The record on which to evaluate the feedback\nfunctions.\n\napp (App, optional): The app that produced the given record.\nIf not provided, it is looked up from the given database `db`.\n\nfeedback_functions (Sequence[Feedback]): A collection of feedback\nfunctions to evaluate.\n
Yields FeedbackResult, one for each element of feedback_functions potentially in random order.
Source code in
trulens_eval/trulens_eval/tru.py def run_feedback_functions(\n self,\n record: Record,\n feedback_functions: Sequence[Feedback],\n app: Optional[AppDefinition] = None,\n) -> Iterable[FeedbackResult]:\n \"\"\"\n Run a collection of feedback functions and report their result.\n\n Parameters:\n\n record (Record): The record on which to evaluate the feedback\n functions.\n\n app (App, optional): The app that produced the given record.\n If not provided, it is looked up from the given database `db`.\n\n feedback_functions (Sequence[Feedback]): A collection of feedback\n functions to evaluate.\n\n Yields `FeedbackResult`, one for each element of `feedback_functions`\n potentially in random order.\n \"\"\"\n\n for res in as_completed(self._submit_feedback_functions(\n record=record, feedback_functions=feedback_functions, app=app)):\n\n yield res.result()[1]\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.start_evaluator","title":"
start_evaluator(restart=False, fork=False)","text":"
Start a deferred feedback function evaluation thread.
Source code in
trulens_eval/trulens_eval/tru.py def start_evaluator(self,\n restart=False,\n fork=False) -> Union[Process, Thread]:\n \"\"\"\n Start a deferred feedback function evaluation thread.\n \"\"\"\n\n assert not fork, \"Fork mode not yet implemented.\"\n\n if self.evaluator_proc is not None:\n if restart:\n self.stop_evaluator()\n else:\n raise RuntimeError(\n \"Evaluator is already running in this process.\"\n )\n\n if not fork:\n self.evaluator_stop = threading.Event()\n\n def runloop():\n assert self.evaluator_stop is not None\n\n while fork or not self.evaluator_stop.is_set():\n futures = Feedback.evaluate_deferred(tru=self)\n\n if len(futures) > 0:\n print(\n f\"{UNICODE_YIELD}{UNICODE_YIELD}{UNICODE_YIELD} Started {len(futures)} deferred feedback functions.\"\n )\n wait(futures)\n print(\n f\"{UNICODE_CHECK}{UNICODE_CHECK}{UNICODE_CHECK} Finished evaluating deferred feedback functions.\"\n )\n\n if fork:\n sleep(10)\n else:\n self.evaluator_stop.wait(10)\n\n print(\"Evaluator stopped.\")\n\n if fork:\n proc = Process(target=runloop)\n else:\n proc = Thread(target=runloop)\n proc.daemon = True\n\n # Start a persistent thread or process that evaluates feedback functions.\n\n self.evaluator_proc = proc\n proc.start()\n\n return proc\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.stop_dashboard","title":"
stop_dashboard(force=False)","text":"
Stop existing dashboard(s) if running.
Args:
- force: bool: Also try to find any other dashboard processes not\n started in this notebook and shut them down too.\n
Raises:
- ValueError: Dashboard is not running.\n
Source code in
trulens_eval/trulens_eval/tru.py def stop_dashboard(self, force: bool = False) -> None:\n \"\"\"\n Stop existing dashboard(s) if running.\n\n Args:\n\n - force: bool: Also try to find any other dashboard processes not\n started in this notebook and shut them down too.\n\n Raises:\n\n - ValueError: Dashboard is not running.\n \"\"\"\n if Tru.dashboard_proc is None:\n if not force:\n raise ValueError(\n \"Dashboard not running in this workspace. \"\n \"You may be able to shut other instances by setting the `force` flag.\"\n )\n\n else:\n if sys.platform.startswith(\"win\"):\n raise RuntimeError(\n \"Force stop option is not supported on windows.\"\n )\n\n print(\"Force stopping dashboard ...\")\n import os\n import pwd # PROBLEM: does not exist on windows\n\n import psutil\n username = pwd.getpwuid(os.getuid())[0]\n for p in psutil.process_iter():\n try:\n cmd = \" \".join(p.cmdline())\n if \"streamlit\" in cmd and \"Leaderboard.py\" in cmd and p.username(\n ) == username:\n print(f\"killing {p}\")\n p.kill()\n except Exception as e:\n continue\n\n else:\n Tru.dashboard_proc.kill()\n Tru.dashboard_proc = None\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.stop_evaluator","title":"
stop_evaluator()","text":"
Stop the deferred feedback evaluation thread.
Source code in
trulens_eval/trulens_eval/tru.py def stop_evaluator(self):\n \"\"\"\n Stop the deferred feedback evaluation thread.\n \"\"\"\n\n if self.evaluator_proc is None:\n raise RuntimeError(\"Evaluator not running this process.\")\n\n if isinstance(self.evaluator_proc, Process):\n self.evaluator_proc.terminate()\n\n elif isinstance(self.evaluator_proc, Thread):\n self.evaluator_stop.set()\n self.evaluator_proc.join()\n self.evaluator_stop = None\n\n self.evaluator_proc = None\n
"},{"location":"trulens_eval/api/trubasicapp/","title":"Tru Basic App","text":""},{"location":"trulens_eval/api/trubasicapp/#trulens_eval.trulens_eval.tru_basic_app--basic-input-output-instrumentation-and-monitoring","title":"Basic input output instrumentation and monitoring.","text":""},{"location":"trulens_eval/api/trubasicapp/#trulens_eval.trulens_eval.tru_basic_app.TruBasicApp","title":"
TruBasicApp","text":"
Bases: App
Instantiates a Basic app that makes little assumptions. Assumes input text and output text.
Usage:
def custom_application(prompt: str) -> str:\n return \"a response\"\n\nfrom trulens_eval import TruBasicApp\n# f_lang_match, f_qa_relevance, f_qs_relevance are feedback functions\ntru_recorder = TruBasicApp(custom_application, \n app_id=\"Custom Application v1\",\n feedbacks=[f_lang_match, f_qa_relevance, f_qs_relevance])\n\n# Basic app works by turning your callable into an app\n# This app is accessbile with the `app` attribute in the recorder\nwith tru_recorder as recording:\n tru_recorder.app(question)\n\ntru_record = recording.records[0]\n
See Feedback Functions for instantiating feedback functions.
Parameters:
Name Type Description Default
text_to_text Callable A text to text callable.
None Source code in
trulens_eval/trulens_eval/tru_basic_app.py class TruBasicApp(App):\n \"\"\"Instantiates a Basic app that makes little assumptions. Assumes input text and output text.\n\n **Usage:**\n\n ```\n def custom_application(prompt: str) -> str:\n return \"a response\"\n\n from trulens_eval import TruBasicApp\n # f_lang_match, f_qa_relevance, f_qs_relevance are feedback functions\n tru_recorder = TruBasicApp(custom_application, \n app_id=\"Custom Application v1\",\n feedbacks=[f_lang_match, f_qa_relevance, f_qs_relevance])\n\n # Basic app works by turning your callable into an app\n # This app is accessbile with the `app` attribute in the recorder\n with tru_recorder as recording:\n tru_recorder.app(question)\n\n tru_record = recording.records[0]\n\n ```\n See [Feedback Functions](https://www.trulens.org/trulens_eval/api/feedback/) for instantiating feedback functions.\n\n Args:\n text_to_text (Callable): A text to text callable.\n \"\"\"\n app: TruWrapperApp\n\n root_callable: ClassVar[FunctionOrMethod] = Field(\n default_factory=lambda: FunctionOrMethod.\n of_callable(TruWrapperApp._call),\n const=True\n )\n\n def __init__(\n self,\n text_to_text: Optional[Callable] = None,\n app: Optional[TruWrapperApp] = None,\n **kwargs\n ):\n \"\"\"\n Wrap a callable for monitoring.\n\n Arguments:\n - text_to_text: A function with signature string to string.\n - More args in App\n - More args in AppDefinition\n - More args in WithClassInfo\n \"\"\"\n\n super().update_forward_refs()\n if text_to_text is not None:\n app = TruWrapperApp(text_to_text)\n else:\n assert app is not None, \"Need to provide either `app: TruWrapperApp` or a `text_to_text: Callable`.\"\n\n kwargs['app'] = app\n kwargs['root_class'] = Class.of_object(app)\n kwargs['instrument'] = TruBasicCallableInstrument(app=self)\n\n super().__init__(**kwargs)\n\n # Setup the DB-related things:\n self.post_init()\n\n def main_call(self, human: str) -> str:\n # If available, a single text to a single text invocation of this app.\n\n return self.app._call(human)\n\n async def main_acall(self, human: str) -> str:\n # If available, a single text to a single text invocation of this app.\n raise NotImplementedError()\n\n def main_input(\n self, func: Callable, sig: Signature, bindings: BoundArguments\n ) -> str:\n\n if func == getattr(TruWrapperApp._call, Instrument.INSTRUMENT):\n # If func is the wrapper app _call, replace the signature and\n # bindings based on the actual containing callable instead of\n # self.app._call . This needs to be done since the a TruWrapperApp\n # may be wrapping apps with different signatures on their callables\n # so TruWrapperApp._call cannot have a consistent signature\n # statically. Note also we are looking up the Instrument.INSTRUMENT\n # attribute here since the method is instrumented and overridden by\n # another wrapper in the process with the original accessible at\n # this attribute.\n\n sig = signature(self.app._call_fn)\n # Skipping self as TruWrapperApp._call takes in self, but\n # self.app._call_fn does not.\n bindings = sig.bind(*bindings.args[1:], **bindings.kwargs)\n\n return super().main_input(func, sig, bindings)\n\n def call_with_record(self, *args, **kwargs):\n \"\"\"\n Run the callable with the given arguments. Note that the wrapped\n callable is expected to take in a single string.\n\n Returns:\n dict: record metadata\n \"\"\"\n # NOTE: Actually text_to_text can take in more args.\n\n self._with_dep_message(method=\"call\", is_async=False, with_record=True)\n\n return self.with_record(self.app._call, *args, **kwargs)\n
"},{"location":"trulens_eval/api/trubasicapp/#trulens_eval.trulens_eval.tru_basic_app.TruBasicApp.__init__","title":"
__init__(text_to_text=None, app=None, **kwargs)","text":"
Wrap a callable for monitoring.
Arguments: - text_to_text: A function with signature string to string. - More args in App - More args in AppDefinition - More args in WithClassInfo
Source code in
trulens_eval/trulens_eval/tru_basic_app.py def __init__(\n self,\n text_to_text: Optional[Callable] = None,\n app: Optional[TruWrapperApp] = None,\n **kwargs\n):\n \"\"\"\n Wrap a callable for monitoring.\n\n Arguments:\n - text_to_text: A function with signature string to string.\n - More args in App\n - More args in AppDefinition\n - More args in WithClassInfo\n \"\"\"\n\n super().update_forward_refs()\n if text_to_text is not None:\n app = TruWrapperApp(text_to_text)\n else:\n assert app is not None, \"Need to provide either `app: TruWrapperApp` or a `text_to_text: Callable`.\"\n\n kwargs['app'] = app\n kwargs['root_class'] = Class.of_object(app)\n kwargs['instrument'] = TruBasicCallableInstrument(app=self)\n\n super().__init__(**kwargs)\n\n # Setup the DB-related things:\n self.post_init()\n
"},{"location":"trulens_eval/api/trubasicapp/#trulens_eval.trulens_eval.tru_basic_app.TruBasicApp.call_with_record","title":"
call_with_record(*args, **kwargs)","text":"
Run the callable with the given arguments. Note that the wrapped callable is expected to take in a single string.
Returns:
Name Type Description
dict record metadata
Source code in
trulens_eval/trulens_eval/tru_basic_app.py def call_with_record(self, *args, **kwargs):\n \"\"\"\n Run the callable with the given arguments. Note that the wrapped\n callable is expected to take in a single string.\n\n Returns:\n dict: record metadata\n \"\"\"\n # NOTE: Actually text_to_text can take in more args.\n\n self._with_dep_message(method=\"call\", is_async=False, with_record=True)\n\n return self.with_record(self.app._call, *args, **kwargs)\n
"},{"location":"trulens_eval/api/truchain/","title":"Tru Chain","text":""},{"location":"trulens_eval/api/truchain/#trulens_eval.trulens_eval.tru_chain--langchain-instrumentation-and-monitoring","title":"Langchain instrumentation and monitoring.","text":""},{"location":"trulens_eval/api/truchain/#trulens_eval.trulens_eval.tru_chain.TruChain","title":"
TruChain","text":"
Bases: App
Instantiates the Langchain Wrapper.
Usage:
Langchain Code: Langchain Quickstart
# Code snippet taken from langchain 0.0.281 (API subject to change with new versions)\nfrom langchain.chains import LLMChain\nfrom langchain.llms import OpenAI\nfrom langchain.prompts.chat import ChatPromptTemplate\nfrom langchain.prompts.chat import HumanMessagePromptTemplate\nfrom langchain.prompts.chat import PromptTemplate\n\nfull_prompt = HumanMessagePromptTemplate(\n prompt=PromptTemplate(\n template=\n \"Provide a helpful response with relevant background information for the following: {prompt}\",\n input_variables=[\"prompt\"],\n )\n)\n\nchat_prompt_template = ChatPromptTemplate.from_messages([full_prompt])\n\nllm = OpenAI(temperature=0.9, max_tokens=128)\n\nchain = LLMChain(llm=llm, prompt=chat_prompt_template, verbose=True)\n
Trulens Eval Code:
from trulens_eval import TruChain\n# f_lang_match, f_qa_relevance, f_qs_relevance are feedback functions\ntru_recorder = TruChain(\n chain,\n app_id='Chain1_ChatApplication',\n feedbacks=[f_lang_match, f_qa_relevance, f_qs_relevance])\n)\nwith tru_recorder as recording:\n chain(\"\"What is langchain?\")\n\ntru_record = recording.records[0]\n\n# To add record metadata \nwith tru_recorder as recording:\n recording.record_metadata=\"this is metadata for all records in this context that follow this line\"\n chain(\"What is langchain?\")\n recording.record_metadata=\"this is different metadata for all records in this context that follow this line\"\n chain(\"Where do I download langchain?\")\n
See Feedback Functions for instantiating feedback functions.
Parameters:
Name Type Description Default
app Chain A langchain application.
required Source code in
trulens_eval/trulens_eval/tru_chain.py class TruChain(App):\n \"\"\"Instantiates the Langchain Wrapper.\n\n **Usage:**\n\n Langchain Code: [Langchain Quickstart](https://python.langchain.com/docs/get_started/quickstart)\n ```\n # Code snippet taken from langchain 0.0.281 (API subject to change with new versions)\n from langchain.chains import LLMChain\n from langchain.llms import OpenAI\n from langchain.prompts.chat import ChatPromptTemplate\n from langchain.prompts.chat import HumanMessagePromptTemplate\n from langchain.prompts.chat import PromptTemplate\n\n full_prompt = HumanMessagePromptTemplate(\n prompt=PromptTemplate(\n template=\n \"Provide a helpful response with relevant background information for the following: {prompt}\",\n input_variables=[\"prompt\"],\n )\n )\n\n chat_prompt_template = ChatPromptTemplate.from_messages([full_prompt])\n\n llm = OpenAI(temperature=0.9, max_tokens=128)\n\n chain = LLMChain(llm=llm, prompt=chat_prompt_template, verbose=True)\n\n ```\n\n Trulens Eval Code:\n ```\n\n from trulens_eval import TruChain\n # f_lang_match, f_qa_relevance, f_qs_relevance are feedback functions\n tru_recorder = TruChain(\n chain,\n app_id='Chain1_ChatApplication',\n feedbacks=[f_lang_match, f_qa_relevance, f_qs_relevance])\n )\n with tru_recorder as recording:\n chain(\"\"What is langchain?\")\n\n tru_record = recording.records[0]\n\n # To add record metadata \n with tru_recorder as recording:\n recording.record_metadata=\"this is metadata for all records in this context that follow this line\"\n chain(\"What is langchain?\")\n recording.record_metadata=\"this is different metadata for all records in this context that follow this line\"\n chain(\"Where do I download langchain?\")\n ```\n See [Feedback Functions](https://www.trulens.org/trulens_eval/api/feedback/) for instantiating feedback functions.\n\n Args:\n app (Chain): A langchain application.\n \"\"\"\n\n app: Chain\n\n # TODO: what if _acall is being used instead?\n root_callable: ClassVar[FunctionOrMethod] = Field(\n default_factory=lambda: FunctionOrMethod.of_callable(TruChain._call),\n const=True\n )\n\n # Normally pydantic does not like positional args but chain here is\n # important enough to make an exception.\n def __init__(self, app: Chain, **kwargs):\n \"\"\"\n Wrap a langchain chain for monitoring.\n\n Arguments:\n - app: Chain -- the chain to wrap.\n - More args in App\n - More args in AppDefinition\n - More args in WithClassInfo\n \"\"\"\n\n super().update_forward_refs()\n\n # TruChain specific:\n kwargs['app'] = app\n kwargs['root_class'] = Class.of_object(app)\n kwargs['instrument'] = LangChainInstrument(app=self)\n\n super().__init__(**kwargs)\n\n self.post_init()\n\n # TODEP\n # Chain requirement\n @property\n def _chain_type(self):\n return \"TruChain\"\n\n # TODEP\n # Chain requirement\n @property\n def input_keys(self) -> List[str]:\n return self.app.input_keys\n\n # TODEP\n # Chain requirement\n @property\n def output_keys(self) -> List[str]:\n return self.app.output_keys\n\n def main_input(\n self, func: Callable, sig: Signature, bindings: BoundArguments\n ) -> str:\n \"\"\"\n Determine the main input string for the given function `func` with\n signature `sig` if it is to be called with the given bindings\n `bindings`.\n \"\"\"\n\n if 'inputs' in bindings.arguments:\n # langchain specific:\n ins = self.app.prep_inputs(bindings.arguments['inputs'])\n\n if len(self.app.input_keys) == 0:\n logger.warning(\n \"langchain app has no inputs. `main_input` will be `None`.\"\n )\n return None\n\n return ins[self.app.input_keys[0]]\n\n return App.main_input(self, func, sig, bindings)\n\n def main_output(\n self, func: Callable, sig: Signature, bindings: BoundArguments, ret: Any\n ) -> str:\n \"\"\"\n Determine the main out string for the given function `func` with\n signature `sig` after it is called with the given `bindings` and has\n returned `ret`.\n \"\"\"\n\n if isinstance(ret, Dict):\n # langchain specific:\n if self.app.output_keys[0] in ret:\n return ret[self.app.output_keys[0]]\n\n return App.main_output(self, func, sig, bindings, ret)\n\n def main_call(self, human: str):\n # If available, a single text to a single text invocation of this app.\n\n out_key = self.app.output_keys[0]\n\n return self.app(human)[out_key]\n\n async def main_acall(self, human: str):\n # If available, a single text to a single text invocation of this app.\n\n out_key = self.app.output_keys[0]\n\n return await self._acall(human)[out_key]\n\n def __getattr__(self, __name: str) -> Any:\n # A message for cases where a user calls something that the wrapped\n # chain has but we do not wrap yet.\n\n if hasattr(self.app, __name):\n return RuntimeError(\n f\"TruChain has no attribute {__name} but the wrapped app ({type(self.app)}) does. \",\n f\"If you are calling a {type(self.app)} method, retrieve it from that app instead of from `TruChain`. \"\n f\"TruChain presently only wraps Chain.__call__, Chain._call, and Chain._acall .\"\n )\n else:\n raise RuntimeError(f\"TruChain has no attribute named {__name}.\")\n\n # NOTE: Input signature compatible with langchain.chains.base.Chain.acall\n # TODEP\n async def acall_with_record(self, *args, **kwargs) -> Tuple[Any, Record]:\n \"\"\"\n Run the chain acall method and also return a record metadata object.\n \"\"\"\n\n self._with_dep_message(method=\"acall\", is_async=True, with_record=True)\n\n return await self.awith_record(self.app.acall, *args, **kwargs)\n\n # NOTE: Input signature compatible with langchain.chains.base.Chain.__call__\n # TODEP\n def call_with_record(self, *args, **kwargs) -> Tuple[Any, Record]:\n \"\"\"\n Run the chain call method and also return a record metadata object.\n \"\"\"\n\n self._with_dep_message(\n method=\"__call__\", is_async=False, with_record=True\n )\n\n return self.with_record(self.app.__call__, *args, **kwargs)\n\n # TODEP\n # Mimics Chain\n def __call__(self, *args, **kwargs) -> Dict[str, Any]:\n \"\"\"\n Wrapped call to self.app._call with instrumentation. If you need to\n get the record, use `call_with_record` instead. \n \"\"\"\n\n self._with_dep_message(\n method=\"__call__\", is_async=False, with_record=False\n )\n\n return self.with_(self.app, *args, **kwargs)\n\n # TODEP\n # Chain requirement\n def _call(self, *args, **kwargs) -> Any:\n\n self._with_dep_message(\n method=\"_call\", is_async=False, with_record=False\n )\n\n ret, _ = self.with_(self.app._call, *args, **kwargs)\n\n return ret\n\n # TODEP\n # Optional Chain requirement\n async def _acall(self, *args, **kwargs) -> Any:\n\n self._with_dep_message(\n method=\"_acall\", is_async=True, with_record=False\n )\n\n ret, _ = await self.awith_(self.app.acall, *args, **kwargs)\n\n return ret\n
"},{"location":"trulens_eval/api/truchain/#trulens_eval.trulens_eval.tru_chain.TruChain.__call__","title":"
__call__(*args, **kwargs)","text":"
Wrapped call to self.app._call with instrumentation. If you need to get the record, use call_with_record instead.
Source code in
trulens_eval/trulens_eval/tru_chain.py def __call__(self, *args, **kwargs) -> Dict[str, Any]:\n \"\"\"\n Wrapped call to self.app._call with instrumentation. If you need to\n get the record, use `call_with_record` instead. \n \"\"\"\n\n self._with_dep_message(\n method=\"__call__\", is_async=False, with_record=False\n )\n\n return self.with_(self.app, *args, **kwargs)\n
"},{"location":"trulens_eval/api/truchain/#trulens_eval.trulens_eval.tru_chain.TruChain.__init__","title":"
__init__(app, **kwargs)","text":"
Wrap a langchain chain for monitoring.
Arguments: - app: Chain -- the chain to wrap. - More args in App - More args in AppDefinition - More args in WithClassInfo
Source code in
trulens_eval/trulens_eval/tru_chain.py def __init__(self, app: Chain, **kwargs):\n \"\"\"\n Wrap a langchain chain for monitoring.\n\n Arguments:\n - app: Chain -- the chain to wrap.\n - More args in App\n - More args in AppDefinition\n - More args in WithClassInfo\n \"\"\"\n\n super().update_forward_refs()\n\n # TruChain specific:\n kwargs['app'] = app\n kwargs['root_class'] = Class.of_object(app)\n kwargs['instrument'] = LangChainInstrument(app=self)\n\n super().__init__(**kwargs)\n\n self.post_init()\n
"},{"location":"trulens_eval/api/truchain/#trulens_eval.trulens_eval.tru_chain.TruChain.acall_with_record","title":"
acall_with_record(*args, **kwargs) async","text":"
Run the chain acall method and also return a record metadata object.
Source code in
trulens_eval/trulens_eval/tru_chain.py async def acall_with_record(self, *args, **kwargs) -> Tuple[Any, Record]:\n \"\"\"\n Run the chain acall method and also return a record metadata object.\n \"\"\"\n\n self._with_dep_message(method=\"acall\", is_async=True, with_record=True)\n\n return await self.awith_record(self.app.acall, *args, **kwargs)\n
"},{"location":"trulens_eval/api/truchain/#trulens_eval.trulens_eval.tru_chain.TruChain.call_with_record","title":"
call_with_record(*args, **kwargs)","text":"
Run the chain call method and also return a record metadata object.
Source code in
trulens_eval/trulens_eval/tru_chain.py def call_with_record(self, *args, **kwargs) -> Tuple[Any, Record]:\n \"\"\"\n Run the chain call method and also return a record metadata object.\n \"\"\"\n\n self._with_dep_message(\n method=\"__call__\", is_async=False, with_record=True\n )\n\n return self.with_record(self.app.__call__, *args, **kwargs)\n
"},{"location":"trulens_eval/api/truchain/#trulens_eval.trulens_eval.tru_chain.TruChain.main_input","title":"
main_input(func, sig, bindings)","text":"
Determine the main input string for the given function func with signature sig if it is to be called with the given bindings bindings.
Source code in
trulens_eval/trulens_eval/tru_chain.py def main_input(\n self, func: Callable, sig: Signature, bindings: BoundArguments\n) -> str:\n \"\"\"\n Determine the main input string for the given function `func` with\n signature `sig` if it is to be called with the given bindings\n `bindings`.\n \"\"\"\n\n if 'inputs' in bindings.arguments:\n # langchain specific:\n ins = self.app.prep_inputs(bindings.arguments['inputs'])\n\n if len(self.app.input_keys) == 0:\n logger.warning(\n \"langchain app has no inputs. `main_input` will be `None`.\"\n )\n return None\n\n return ins[self.app.input_keys[0]]\n\n return App.main_input(self, func, sig, bindings)\n
"},{"location":"trulens_eval/api/truchain/#trulens_eval.trulens_eval.tru_chain.TruChain.main_output","title":"
main_output(func, sig, bindings, ret)","text":"
Determine the main out string for the given function func with signature sig after it is called with the given bindings and has returned ret.
Source code in
trulens_eval/trulens_eval/tru_chain.py def main_output(\n self, func: Callable, sig: Signature, bindings: BoundArguments, ret: Any\n) -> str:\n \"\"\"\n Determine the main out string for the given function `func` with\n signature `sig` after it is called with the given `bindings` and has\n returned `ret`.\n \"\"\"\n\n if isinstance(ret, Dict):\n # langchain specific:\n if self.app.output_keys[0] in ret:\n return ret[self.app.output_keys[0]]\n\n return App.main_output(self, func, sig, bindings, ret)\n
"},{"location":"trulens_eval/api/trucustom/","title":"Tru Custom App","text":""},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app--custom-class-apps","title":"Custom class Apps","text":"
This wrapper covers apps that are not based on one of the high-level frameworks such as langchain or llama-index. We instead assume that some python class or classes implements an app which has similar functionality to LLM apps coded in the high-level frameworks in that it generally processes text queries to produce text outputs while making intermediate queries to things like LLMs, vector DBs, and similar.
"},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app--example-usage","title":"Example Usage","text":"
Consider a mock question-answering app with a context retriever component coded up as two classes in two python, CustomApp and CustomRetriever:
"},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app--custom_apppy","title":"
custom_app.py","text":"
from trulens_eval.tru_custom_app import instrument\nfrom custom_retriever import CustomRetriever \n\n\nclass CustomApp:\n # NOTE: No restriction on this class.\n\n def __init__(self):\n self.retriever = CustomRetriever()\n\n @instrument\n def retrieve_chunks(self, data):\n return self.retriever.retrieve_chunks(data)\n\n @instrument\n def respond_to_query(self, input):\n chunks = self.retrieve_chunks(input) output = f\"The answer to {input} is\n probably {chunks[0]} or something ...\" return output\n
"},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app--custom_retrieverpy","title":"
custom_retriever.py","text":"
from trulens_eval.tru_custom_app import instrument\n\nclass CustomRetriever:\n # NOTE: No restriction on this class either.\n\n @instrument\n def retrieve_chunks(self, data):\n return [\n f\"Relevant chunk: {data.upper()}\", f\"Relevant chunk: {data[::-1]}\"\n ]\n
The core tool for instrumenting these classes is the instrument method (actually class, but details are not important here). trulens needs to be aware of two high-level concepts to usefully monitor the app: components and methods used by components. The instrument must decorate each method that the user wishes to watch (for it to show up on the dashboard). In the example, all of the functionalities are decorated. Additionally, the owner classes of any decorated method is viewed as an app component. In this case CustomApp and CustomRetriever are components.
Following the instrumentation, the app can be used with or without tracking:
"},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app--examplepy","title":"
example.py","text":"
from custom_app import CustomApp from trulens_eval.tru_custom_app\nimport TruCustomApp\n\nca = CustomApp()\n\n# Normal app Usage:\nresponse = ca.respond_to_query(\"What is the capital of Indonesia?\")\n\n# Wrapping app with `TruCustomApp`: \nta = TruCustomApp(ca)\n\n# Wrapped Usage: must use the general `with_record` (or `awith_record`) method:\nresponse, record = ta.with_record(\n ca.respond_to_query, input=\"What is the capital of Indonesia?\"\n)\n
The with_record use above returns both the response of the app normally produces as well as the record of the app as is the case with the higher-level wrappers. TruCustomApp constructor arguments are like in those higher-level apps as well including the feedback functions, metadata, etc.
"},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app--instrumenting-3rd-party-classes","title":"Instrumenting 3
rd party classes","text":"
In cases you do not have access to a class to make the necessary decorations for tracking, you can instead use one of the static methods of instrument, for example, the alterative for making sure the custom retriever gets instrumented is via:
# custom_app.py`:\n\nfrom trulens_eval.tru_custom_app import instrument\nfrom somepackage.from custom_retriever import CustomRetriever\n\ninstrument.method(CustomRetriever, \"retrieve_chunks\")\n\n# ... rest of the custom class follows ...\n
"},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app--api-usage-tracking","title":"API Usage Tracking","text":"
Uses of python libraries for common LLMs like OpenAI are tracked in custom class apps.
"},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app--covered-llm-libraries","title":"Covered LLM Libraries","text":"
- Official OpenAI python package (https://github.com/openai/openai-python).
"},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app--huggingface","title":"Huggingface","text":"
Uses of huggingface inference APIs are tracked as long as requests are made through the requests class's post method to the URL https://api-inference.huggingface.co .
"},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app--limitations","title":"Limitations","text":"
-
Tracked (instrumented) components must be accessible through other tracked components. Specifically, an app cannot have a custom class that is not instrumented but that contains an instrumented class. The inner instrumented class will not be found by trulens.
-
All tracked components are categorized as \"Custom\" (as opposed to Template, LLM, etc.). That is, there is no categorization available for custom components. They will all show up as \"uncategorized\" in the dashboard.
-
Non json-like contents of components (that themselves are not components) are not recorded or available in dashboard. This can be alleviated to some extent with the app_extra_json argument to TruCustomClass as it allows one to specify in the form of json additional information to store alongside the component hierarchy. Json-like (json bases like string, int, and containers like sequences and dicts are included).
"},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app--what-can-go-wrong","title":"What can go wrong","text":"
- If a
with_record or awith_record call does not encounter any instrumented method, it will raise an error. You can check which methods are instrumented using App.print_instrumented. You may have forgotten to decorate relevant methods with @instrument.
app.print_instrumented()\n\n### output example:\nComponents:\n TruCustomApp (Other) at 0x171bd3380 with path *.__app__\n CustomApp (Custom) at 0x12114b820 with path *.__app__.app\n CustomLLM (Custom) at 0x12114be50 with path *.__app__.app.llm\n CustomMemory (Custom) at 0x12114bf40 with path *.__app__.app.memory\n CustomRetriever (Custom) at 0x12114bd60 with path *.__app__.app.retriever\n CustomTemplate (Custom) at 0x12114bf10 with path *.__app__.app.template\n\nMethods:\nObject at 0x12114b820:\n <function CustomApp.retrieve_chunks at 0x299132ca0> with path *.__app__.app\n <function CustomApp.respond_to_query at 0x299132d30> with path *.__app__.app\n <function CustomApp.arespond_to_query at 0x299132dc0> with path *.__app__.app\nObject at 0x12114be50:\n <function CustomLLM.generate at 0x299106b80> with path *.__app__.app.llm\nObject at 0x12114bf40:\n <function CustomMemory.remember at 0x299132670> with path *.__app__.app.memory\nObject at 0x12114bd60:\n <function CustomRetriever.retrieve_chunks at 0x299132790> with path *.__app__.app.retriever\nObject at 0x12114bf10:\n <function CustomTemplate.fill at 0x299132a60> with path *.__app__.app.template\n
- If an instrumented / decorated method's owner object cannot be found when traversing your custom class, you will get a warning. This may be ok in the end but may be indicative of a problem. Specifically, note the \"Tracked\" limitation above. You can also use the
app_extra_json argument to App / TruCustomApp to provide a structure to stand in place for (or augment) the data produced by walking over instrumented components to make sure this hierarchy contains the owner of each instrumented method.
The owner-not-found error looks like this:
Function <function CustomRetriever.retrieve_chunks at 0x177935d30> was not found during instrumentation walk. Make sure it is accessible by traversing app <custom_app.CustomApp object at 0x112a005b0> or provide a bound method for it as TruCustomApp constructor argument `methods_to_instrument`.\nFunction <function CustomTemplate.fill at 0x1779474c0> was not found during instrumentation walk. Make sure it is accessible by traversing app <custom_app.CustomApp object at 0x112a005b0> or provide a bound method for it as TruCustomApp constructor argument `methods_to_instrument`.\nFunction <function CustomLLM.generate at 0x1779471f0> was not found during instrumentation walk. Make sure it is accessible by traversing app <custom_app.CustomApp object at 0x112a005b0> or provide a bound method for it as TruCustomApp constructor argument `methods_to_instrument`.\n
Subsequent attempts at with_record/awith_record may result in the \"Empty record\" exception.
- Usage tracking not tracking. We presently have limited coverage over which APIs we track and make some assumptions with regards to accessible APIs through lower-level interfaces. Specifically, we only instrument the
requests module's post method for the lower level tracking. Please file an issue on github with your use cases so we can work out a more complete solution as needed.
"},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app.TruCustomApp","title":"
TruCustomApp","text":"
Bases: App
Instantiates a Custom App that can be tracked as long as methods are decorated with @instrument.
Usage:
from trulens_eval import instrument\n\nclass CustomApp:\n\n def __init__(self):\n self.retriever = CustomRetriever()\n self.llm = CustomLLM()\n self.template = CustomTemplate(\n \"The answer to {question} is probably {answer} or something ...\"\n )\n\n @instrument\n def retrieve_chunks(self, data):\n return self.retriever.retrieve_chunks(data)\n\n @instrument\n def respond_to_query(self, input):\n chunks = self.retrieve_chunks(input)\n answer = self.llm.generate(\",\".join(chunks))\n output = self.template.fill(question=input, answer=answer)\n\n return output\n\nca = CustomApp()\nfrom trulens_eval import TruCustomApp\n# f_lang_match, f_qa_relevance, f_qs_relevance are feedback functions\ntru_recorder = TruCustomApp(ca, \n app_id=\"Custom Application v1\",\n feedbacks=[f_lang_match, f_qa_relevance, f_qs_relevance])\n\nquestion = \"What is the capital of Indonesia?\"\n\n# Normal Usage:\nresponse_normal = ca.respond_to_query(question)\n\n# Instrumented Usage:\nwith tru_recorder as recording:\n ca.respond_to_query(question)\n\ntru_record = recording.records[0]\n\n# To add record metadata \nwith tru_recorder as recording:\n recording.record_metadata=\"this is metadata for all records in this context that follow this line\"\n ca.respond_to_query(\"What is llama 2?\")\n recording.record_metadata=\"this is different metadata for all records in this context that follow this line\"\n ca.respond_to_query(\"Where do I download llama 2?\")\n
See Feedback Functions for instantiating feedback functions.
Parameters:
Name Type Description Default
app Any Any class
required Source code in
trulens_eval/trulens_eval/tru_custom_app.py class TruCustomApp(App):\n \"\"\"Instantiates a Custom App that can be tracked as long as methods are decorated with @instrument.\n\n **Usage:**\n\n ```\n from trulens_eval import instrument\n\n class CustomApp:\n\n def __init__(self):\n self.retriever = CustomRetriever()\n self.llm = CustomLLM()\n self.template = CustomTemplate(\n \"The answer to {question} is probably {answer} or something ...\"\n )\n\n @instrument\n def retrieve_chunks(self, data):\n return self.retriever.retrieve_chunks(data)\n\n @instrument\n def respond_to_query(self, input):\n chunks = self.retrieve_chunks(input)\n answer = self.llm.generate(\",\".join(chunks))\n output = self.template.fill(question=input, answer=answer)\n\n return output\n\n ca = CustomApp()\n from trulens_eval import TruCustomApp\n # f_lang_match, f_qa_relevance, f_qs_relevance are feedback functions\n tru_recorder = TruCustomApp(ca, \n app_id=\"Custom Application v1\",\n feedbacks=[f_lang_match, f_qa_relevance, f_qs_relevance])\n\n question = \"What is the capital of Indonesia?\"\n\n # Normal Usage:\n response_normal = ca.respond_to_query(question)\n\n # Instrumented Usage:\n with tru_recorder as recording:\n ca.respond_to_query(question)\n\n tru_record = recording.records[0]\n\n # To add record metadata \n with tru_recorder as recording:\n recording.record_metadata=\"this is metadata for all records in this context that follow this line\"\n ca.respond_to_query(\"What is llama 2?\")\n recording.record_metadata=\"this is different metadata for all records in this context that follow this line\"\n ca.respond_to_query(\"Where do I download llama 2?\")\n\n ```\n See [Feedback Functions](https://www.trulens.org/trulens_eval/api/feedback/) for instantiating feedback functions.\n\n Args:\n app (Any): Any class\n \"\"\"\n app: Any\n\n root_callable: ClassVar[FunctionOrMethod] = Field(None)\n\n # Methods marked as needing instrumentation. These are checked to make sure\n # the object walk finds them. If not, a message is shown to let user know\n # how to let the TruCustomApp constructor know where these methods are.\n functions_to_instrument: ClassVar[Set[Callable]] = set([])\n\n main_method: Optional[Function] = None # serialized version of the below\n main_method_loaded: Optional[Callable] = Field(exclude=True)\n\n # main_async_method: Optional[Union[Callable, Method]] = None # = Field(exclude=True)\n\n def __init__(self, app: Any, methods_to_instrument=None, **kwargs):\n \"\"\"\n Wrap a custom class for recording.\n\n Arguments:\n - app: Any -- the custom app object being wrapped.\n - More args in App\n - More args in AppDefinition\n - More args in WithClassInfo\n \"\"\"\n\n kwargs['app'] = app\n kwargs['root_class'] = Class.of_object(app)\n\n instrument = Instrument(\n app=self # App mixes in WithInstrumentCallbacks\n )\n kwargs['instrument'] = instrument\n\n if 'main_method' in kwargs:\n main_method = kwargs['main_method']\n\n # TODO: ARGPARSE\n if isinstance(main_method, dict):\n main_method = Function(**main_method)\n\n if isinstance(main_method, Function):\n main_method_loaded = main_method.load()\n main_name = main_method.name\n\n cls = main_method.cls.load()\n mod = main_method.module.load().__name__\n\n else:\n main_name = main_method.__name__\n main_method_loaded = main_method\n\n if not hasattr(main_method_loaded, \"__self__\"):\n raise ValueError(\n \"Please specify `main_method` as a bound method (like `someapp.somemethod` instead of `Someclass.somemethod`).\"\n )\n\n app_self = main_method_loaded.__self__\n\n assert app_self == app, \"`main_method`'s bound self must be the same as `app`.\"\n\n cls = app_self.__class__\n mod = cls.__module__\n\n instrument.include_modules.add(mod)\n instrument.include_classes.add(cls)\n instrument.include_methods[main_name] = lambda o: isinstance(o, cls)\n\n # This does instrumentation:\n super().__init__(**kwargs)\n\n # Needed to split this part to after the instrumentation so that the\n # getattr below gets the instrumented version of main method.\n if 'main_method' in kwargs:\n # Set main_method to the unbound version. Will be passing in app for\n # \"self\" manually when needed.\n main_method_loaded = getattr(cls, main_name)\n\n # This will be serialized as part of this TruCustomApp. Importatly, it is unbound.\n main_method = Function.of_function(main_method_loaded, cls=cls)\n\n self.main_method = main_method\n self.main_method_loaded = main_method_loaded\n\n methods_to_instrument = methods_to_instrument or dict()\n\n # The rest of this code instruments methods explicitly passed to\n # constructor as needing instrumentation and checks that methods\n # decorated with @instrument or passed explicitly belong to some\n # component as per serialized version of this app. If they are not,\n # placeholders are made in `app_extra_json` so that subsequent\n # serialization looks like the components exist.\n json = self.dict()\n\n for m, path in methods_to_instrument.items():\n method_name = m.__name__\n\n full_path = JSONPath().app + path\n\n self.instrument.instrument_method(\n method_name=method_name, obj=m.__self__, query=full_path\n )\n\n # TODO: DEDUP with next condition\n\n # Check whether the path/location of the method is in json serialization and\n # if not, add a placeholder to app_extra_json.\n try:\n next(full_path(json))\n\n print(\n f\"{UNICODE_CHECK} Added method {m.__name__} under component at path {full_path}\"\n )\n\n except Exception:\n logger.warning(\n f\"App has no component at path {full_path} . \"\n f\"Specify the component with the `app_extra_json` argument to TruCustomApp constructor. \"\n f\"Creating a placeholder there for now.\"\n )\n\n path.set(\n self.app_extra_json, {\n PLACEHOLDER:\n \"I was automatically added to `app_extra_json` because there was nothing here to refer to an instrumented method owner.\",\n m.__name__:\n f\"Placeholder for method {m.__name__}.\"\n }\n )\n\n # Check that any functions marked with `TruCustomApp.instrument` has been\n # instrumented as a method under some object.\n for f in TruCustomApp.functions_to_instrument:\n obj_ids_methods_and_full_paths = list(self._get_methods_for_func(f))\n\n if len(obj_ids_methods_and_full_paths) == 0:\n logger.warning(\n f\"Function {f} was not found during instrumentation walk. \"\n f\"Make sure it is accessible by traversing app {app} \"\n f\"or provide a bound method for it as TruCustomApp constructor argument `methods_to_instrument`.\"\n )\n\n else:\n for obj_id, m, full_path in obj_ids_methods_and_full_paths:\n try:\n next(full_path.get(json))\n\n except Exception as e:\n logger.warning(\n f\"App has no component owner of instrumented method {m} at path {full_path}. \"\n f\"Specify the component with the `app_extra_json` argument to TruCustomApp constructor. \"\n f\"Creating a placeholder there for now.\"\n )\n\n path.set(\n self.app_extra_json, {\n PLACEHOLDER:\n \"I was automatically added to `app_extra_json` because there was nothing here to refer to an instrumented method owner.\",\n m.__name__:\n f\"Placeholder for method {m.__name__}.\"\n }\n )\n\n # DB stuff and checks:\n self.post_init()\n\n def __getattr__(self, __name: str) -> Any:\n # A message for cases where a user calls something that the wrapped\n # app has but we do not wrap yet.\n\n print(__name)\n\n if hasattr(self.app, __name):\n return RuntimeError(\n f\"TruCustomApp has no attribute {__name} but the wrapped app ({type(self.app)}) does. \",\n f\"If you are calling a {type(self.app)} method, retrieve it from that app instead of from `TruCustomApp`. \"\n )\n else:\n raise RuntimeError(\n f\"TruCustomApp nor wrapped app have attribute named {__name}.\"\n )\n\n def main_call(self, human: str):\n if self.main_method_loaded is None:\n raise RuntimeError(\n \"`main_method` was not specified so we do not know how to run this app.\"\n )\n\n sig = signature(self.main_method_loaded)\n bindings = sig.bind(self.app, human) # self.app is app's \"self\"\n\n return self.main_method_loaded(*bindings.args, **bindings.kwargs)\n\n \"\"\"\n # Async work ongoing:\n async def main_acall(self, human: str):\n # TODO: work in progress\n\n # must return an async generator of tokens/pieces that can be appended to create the full response\n\n if self.main_async_method is None:\n raise RuntimeError(\n \"`main_async_method` was not specified so we do not know how to run this app.\"\n )\n\n sig = signature(self.main_async_method)\n bindings = sig.bind(self.app, human) # self.app is app's \"self\"\n\n generator = await self.main_async_method(*bindings.args, **bindings.kwargs)\n\n return generator\n \"\"\"\n
"},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app.TruCustomApp.__init__","title":"
__init__(app, methods_to_instrument=None, **kwargs)","text":"
Wrap a custom class for recording.
Arguments: - app: Any -- the custom app object being wrapped. - More args in App - More args in AppDefinition - More args in WithClassInfo
Source code in
trulens_eval/trulens_eval/tru_custom_app.py def __init__(self, app: Any, methods_to_instrument=None, **kwargs):\n \"\"\"\n Wrap a custom class for recording.\n\n Arguments:\n - app: Any -- the custom app object being wrapped.\n - More args in App\n - More args in AppDefinition\n - More args in WithClassInfo\n \"\"\"\n\n kwargs['app'] = app\n kwargs['root_class'] = Class.of_object(app)\n\n instrument = Instrument(\n app=self # App mixes in WithInstrumentCallbacks\n )\n kwargs['instrument'] = instrument\n\n if 'main_method' in kwargs:\n main_method = kwargs['main_method']\n\n # TODO: ARGPARSE\n if isinstance(main_method, dict):\n main_method = Function(**main_method)\n\n if isinstance(main_method, Function):\n main_method_loaded = main_method.load()\n main_name = main_method.name\n\n cls = main_method.cls.load()\n mod = main_method.module.load().__name__\n\n else:\n main_name = main_method.__name__\n main_method_loaded = main_method\n\n if not hasattr(main_method_loaded, \"__self__\"):\n raise ValueError(\n \"Please specify `main_method` as a bound method (like `someapp.somemethod` instead of `Someclass.somemethod`).\"\n )\n\n app_self = main_method_loaded.__self__\n\n assert app_self == app, \"`main_method`'s bound self must be the same as `app`.\"\n\n cls = app_self.__class__\n mod = cls.__module__\n\n instrument.include_modules.add(mod)\n instrument.include_classes.add(cls)\n instrument.include_methods[main_name] = lambda o: isinstance(o, cls)\n\n # This does instrumentation:\n super().__init__(**kwargs)\n\n # Needed to split this part to after the instrumentation so that the\n # getattr below gets the instrumented version of main method.\n if 'main_method' in kwargs:\n # Set main_method to the unbound version. Will be passing in app for\n # \"self\" manually when needed.\n main_method_loaded = getattr(cls, main_name)\n\n # This will be serialized as part of this TruCustomApp. Importatly, it is unbound.\n main_method = Function.of_function(main_method_loaded, cls=cls)\n\n self.main_method = main_method\n self.main_method_loaded = main_method_loaded\n\n methods_to_instrument = methods_to_instrument or dict()\n\n # The rest of this code instruments methods explicitly passed to\n # constructor as needing instrumentation and checks that methods\n # decorated with @instrument or passed explicitly belong to some\n # component as per serialized version of this app. If they are not,\n # placeholders are made in `app_extra_json` so that subsequent\n # serialization looks like the components exist.\n json = self.dict()\n\n for m, path in methods_to_instrument.items():\n method_name = m.__name__\n\n full_path = JSONPath().app + path\n\n self.instrument.instrument_method(\n method_name=method_name, obj=m.__self__, query=full_path\n )\n\n # TODO: DEDUP with next condition\n\n # Check whether the path/location of the method is in json serialization and\n # if not, add a placeholder to app_extra_json.\n try:\n next(full_path(json))\n\n print(\n f\"{UNICODE_CHECK} Added method {m.__name__} under component at path {full_path}\"\n )\n\n except Exception:\n logger.warning(\n f\"App has no component at path {full_path} . \"\n f\"Specify the component with the `app_extra_json` argument to TruCustomApp constructor. \"\n f\"Creating a placeholder there for now.\"\n )\n\n path.set(\n self.app_extra_json, {\n PLACEHOLDER:\n \"I was automatically added to `app_extra_json` because there was nothing here to refer to an instrumented method owner.\",\n m.__name__:\n f\"Placeholder for method {m.__name__}.\"\n }\n )\n\n # Check that any functions marked with `TruCustomApp.instrument` has been\n # instrumented as a method under some object.\n for f in TruCustomApp.functions_to_instrument:\n obj_ids_methods_and_full_paths = list(self._get_methods_for_func(f))\n\n if len(obj_ids_methods_and_full_paths) == 0:\n logger.warning(\n f\"Function {f} was not found during instrumentation walk. \"\n f\"Make sure it is accessible by traversing app {app} \"\n f\"or provide a bound method for it as TruCustomApp constructor argument `methods_to_instrument`.\"\n )\n\n else:\n for obj_id, m, full_path in obj_ids_methods_and_full_paths:\n try:\n next(full_path.get(json))\n\n except Exception as e:\n logger.warning(\n f\"App has no component owner of instrumented method {m} at path {full_path}. \"\n f\"Specify the component with the `app_extra_json` argument to TruCustomApp constructor. \"\n f\"Creating a placeholder there for now.\"\n )\n\n path.set(\n self.app_extra_json, {\n PLACEHOLDER:\n \"I was automatically added to `app_extra_json` because there was nothing here to refer to an instrumented method owner.\",\n m.__name__:\n f\"Placeholder for method {m.__name__}.\"\n }\n )\n\n # DB stuff and checks:\n self.post_init()\n
"},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app.instrument","title":"
instrument","text":"
Bases: instrument
Decorator for marking methods to be instrumented in custom classes that are wrapped by TruCustomApp.
Source code in
trulens_eval/trulens_eval/tru_custom_app.py class instrument(base_instrument):\n \"\"\"\n Decorator for marking methods to be instrumented in custom classes that are\n wrapped by TruCustomApp.\n \"\"\"\n\n @classmethod\n def method(self_class, cls: type, name: str) -> None:\n base_instrument.method(cls, name)\n\n # Also make note of it for verification that it was found by the walk\n # after init.\n TruCustomApp.functions_to_instrument.add(getattr(cls, name))\n
"},{"location":"trulens_eval/api/trullama/","title":"Tru Llama","text":""},{"location":"trulens_eval/api/trullama/#trulens_eval.trulens_eval.tru_llama--llama_index-instrumentation-and-monitoring","title":"Llama_index instrumentation and monitoring.","text":""},{"location":"trulens_eval/api/trullama/#trulens_eval.trulens_eval.tru_llama.TruLlama","title":"
TruLlama","text":"
Bases: App
Instantiates the LLama Index Wrapper.
Usage:
LLama-Index code: LLama Index Quickstart
# Code snippet taken from llama_index 0.8.15 (API subject to change with new versions)\nfrom llama_index import VectorStoreIndex, SimpleWebPageReader\n\ndocuments = SimpleWebPageReader(\n html_to_text=True\n).load_data([\"http://paulgraham.com/worked.html\"])\nindex = VectorStoreIndex.from_documents(documents)\n\nquery_engine = index.as_query_engine()\n
Trulens Eval Code:
from trulens_eval import TruLlama\n# f_lang_match, f_qa_relevance, f_qs_relevance are feedback functions\ntru_recorder = TruLlama(query_engine,\n app_id='LlamaIndex_App1',\n feedbacks=[f_lang_match, f_qa_relevance, f_qs_relevance])\n\nwith tru_recorder as recording:\n query_engine.query(\"What is llama index?\")\n\ntru_record = recording.records[0]\n\n# To add record metadata \nwith tru_recorder as recording:\n recording.record_metadata=\"this is metadata for all records in this context that follow this line\"\n query_engine.query(\"What is llama index?\")\n recording.record_metadata=\"this is different metadata for all records in this context that follow this line\"\n query_engine.query(\"Where do I download llama index?\")\n
See Feedback Functions for instantiating feedback functions.
Parameters:
Name Type Description Default
app BaseQueryEngine A llama index application.
required Source code in
trulens_eval/trulens_eval/tru_llama.py class TruLlama(App):\n \"\"\"Instantiates the LLama Index Wrapper.\n\n **Usage:**\n\n LLama-Index code: [LLama Index Quickstart](https://gpt-index.readthedocs.io/en/stable/getting_started/starter_example.html)\n ```\n # Code snippet taken from llama_index 0.8.15 (API subject to change with new versions)\n from llama_index import VectorStoreIndex, SimpleWebPageReader\n\n documents = SimpleWebPageReader(\n html_to_text=True\n ).load_data([\"http://paulgraham.com/worked.html\"])\n index = VectorStoreIndex.from_documents(documents)\n\n query_engine = index.as_query_engine()\n\n ```\n\n Trulens Eval Code:\n ```\n from trulens_eval import TruLlama\n # f_lang_match, f_qa_relevance, f_qs_relevance are feedback functions\n tru_recorder = TruLlama(query_engine,\n app_id='LlamaIndex_App1',\n feedbacks=[f_lang_match, f_qa_relevance, f_qs_relevance])\n\n with tru_recorder as recording:\n query_engine.query(\"What is llama index?\")\n\n tru_record = recording.records[0]\n\n # To add record metadata \n with tru_recorder as recording:\n recording.record_metadata=\"this is metadata for all records in this context that follow this line\"\n query_engine.query(\"What is llama index?\")\n recording.record_metadata=\"this is different metadata for all records in this context that follow this line\"\n query_engine.query(\"Where do I download llama index?\")\n\n\n ```\n See [Feedback Functions](https://www.trulens.org/trulens_eval/api/feedback/) for instantiating feedback functions.\n\n Args:\n app (BaseQueryEngine): A llama index application.\n \"\"\"\n\n class Config:\n arbitrary_types_allowed = True\n\n app: Union[BaseQueryEngine, BaseChatEngine]\n\n root_callable: ClassVar[FunctionOrMethod] = Field(\n default_factory=lambda: FunctionOrMethod.of_callable(TruLlama.query),\n const=True\n )\n\n def __init__(self, app: BaseQueryEngine, **kwargs):\n super().update_forward_refs()\n\n # TruLlama specific:\n kwargs['app'] = app\n kwargs['root_class'] = Class.of_object(app) # TODO: make class property\n kwargs['instrument'] = LlamaInstrument(app=self)\n\n super().__init__(**kwargs)\n\n self.post_init()\n\n @classmethod\n def select_source_nodes(cls) -> JSONPath:\n \"\"\"\n Get the path to the source nodes in the query output.\n \"\"\"\n return cls.select_outputs().source_nodes[:]\n\n def main_input(\n self, func: Callable, sig: Signature, bindings: BoundArguments\n ) -> str:\n \"\"\"\n Determine the main input string for the given function `func` with\n signature `sig` if it is to be called with the given bindings\n `bindings`.\n \"\"\"\n\n if 'str_or_query_bundle' in bindings.arguments:\n # llama_index specific\n return bindings.arguments['str_or_query_bundle']\n\n elif 'message' in bindings.arguments:\n # llama_index specific\n return bindings.arguments['message']\n\n else:\n\n return App.main_input(self, func, sig, bindings)\n\n def main_output(\n self, func: Callable, sig: Signature, bindings: BoundArguments, ret: Any\n ) -> Optional[str]:\n \"\"\"\n Determine the main out string for the given function `func` with\n signature `sig` after it is called with the given `bindings` and has\n returned `ret`.\n \"\"\"\n\n try:\n attr = self._main_output_attribute(ret)\n\n if attr is not None:\n return getattr(ret, attr)\n else: # attr is None\n return App.main_output(self, func, sig, bindings, ret)\n\n except NotImplementedError:\n return None\n\n def _main_output_attribute(self, ret: Any) -> Optional[str]:\n \"\"\"\n Which attribute in ret contains the main output of this llama_index app.\n \"\"\"\n\n if isinstance(ret, Response): # query, aquery\n return \"response\"\n\n elif isinstance(ret, AgentChatResponse): # chat, achat\n return \"response\"\n\n elif isinstance(ret, (StreamingResponse, StreamingAgentChatResponse)):\n raise NotImplementedError(\n \"App produced a streaming response. \"\n \"Tracking content of streams in llama_index is not yet supported. \"\n \"App main_output will be None.\"\n )\n\n return None\n\n def main_call(self, human: str):\n # If available, a single text to a single text invocation of this app.\n\n if isinstance(self.app, BaseQueryEngine):\n ret = self.app.query(human)\n elif isinstance(self.app, BaseChatEngine):\n ret = self.app.chat(human)\n else:\n raise RuntimeError(\n f\"Do not know what the main method for app of type {type(self.app).__name__} is.\"\n )\n\n try:\n attr = self._main_output_attribute(ret)\n assert attr is not None\n return getattr(ret, attr)\n\n except Exception:\n raise NotImplementedError(\n f\"Do not know what in object of type {type(ret).__name__} is the main app output.\"\n )\n\n async def main_acall(self, human: str):\n # If available, a single text to a single text invocation of this app.\n\n if isinstance(self.app, BaseQueryEngine):\n ret = await self.app.aquery(human)\n elif isinstance(self.app, BaseChatEngine):\n ret = await self.app.achat(human)\n else:\n raise RuntimeError(\n f\"Do not know what the main async method for app of type {type(self.app).__name__} is.\"\n )\n\n try:\n attr = self._main_output_attribute(ret)\n assert attr is not None\n return getattr(ret, attr)\n\n except Exception:\n raise NotImplementedError(\n f\"Do not know what in object of type {type(ret).__name__} is the main app output.\"\n )\n\n # TODEP\n # llama_index.chat_engine.types.BaseChatEngine\n def chat(self, *args, **kwargs) -> AgentChatResponse:\n assert isinstance(self.app, BaseChatEngine)\n\n self._with_dep_message(method=\"chat\", is_async=False, with_record=False)\n\n res, _ = self.chat_with_record(*args, **kwargs)\n return res\n\n # TODEP\n # llama_index.chat_engine.types.BaseChatEngine\n async def achat(self, *args, **kwargs) -> AgentChatResponse:\n assert isinstance(self.app, BaseChatEngine)\n\n self._with_dep_message(method=\"achat\", is_async=True, with_record=False)\n\n res, _ = await self.achat_with_record(*args, **kwargs)\n return res\n\n # TODEP\n # llama_index.chat_engine.types.BaseChatEngine\n def stream_chat(self, *args, **kwargs) -> StreamingAgentChatResponse:\n assert isinstance(self.app, BaseChatEngine)\n\n self._with_dep_message(\n method=\"stream_chat\", is_async=False, with_record=False\n )\n\n res, _ = self.stream_chat_with_record(*args, **kwargs)\n return res\n\n # TODEP\n # llama_index.chat_engine.types.BaseChatEngine\n async def astream_chat(self, *args, **kwargs) -> StreamingAgentChatResponse:\n assert isinstance(self.app, BaseChatEngine)\n\n self._with_dep_message(\n method=\"astream_chat\", is_async=True, with_record=False\n )\n\n res, _ = await self.astream_chat_with_record(*args, **kwargs)\n return res\n\n # TODEP\n # llama_index.indices.query.base.BaseQueryEngine\n def query(self, *args, **kwargs) -> RESPONSE_TYPE:\n\n assert isinstance(self.app, BaseQueryEngine)\n\n self._with_dep_message(\n method=\"query\", is_async=False, with_record=False\n )\n\n res, _ = self.query_with_record(*args, **kwargs)\n return res\n\n # TODEP\n # llama_index.indices.query.base.BaseQueryEngine\n async def aquery(self, *args, **kwargs) -> RESPONSE_TYPE:\n\n assert isinstance(self.app, BaseQueryEngine)\n\n self._with_dep_message(\n method=\"aquery\", is_async=True, with_record=False\n )\n\n res, _ = await self.aquery_with_record(*args, **kwargs)\n return res\n\n # TODEP\n # Mirrors llama_index.indices.query.base.BaseQueryEngine.query .\n def query_with_record(self, *args,\n **kwargs) -> Tuple[RESPONSE_TYPE, Record]:\n\n assert isinstance(self.app, BaseQueryEngine)\n\n self._with_dep_message(method=\"query\", is_async=False, with_record=True)\n\n return self.with_record(self.app.query, *args, **kwargs)\n\n # TODEP\n # Mirrors llama_index.indices.query.base.BaseQueryEngine.aquery .\n async def aquery_with_record(self, *args,\n **kwargs) -> Tuple[RESPONSE_TYPE, Record]:\n assert isinstance(self.app, BaseQueryEngine)\n\n self._with_dep_message(method=\"aquery\", is_async=True, with_record=True)\n\n return await self.awith_record(self.app.aquery, *args, **kwargs)\n\n # TODEP\n # Compatible with llama_index.chat_engine.types.BaseChatEngine.chat .\n def chat_with_record(self, *args,\n **kwargs) -> Tuple[AgentChatResponse, Record]:\n\n assert isinstance(self.app, BaseChatEngine)\n\n self._with_dep_message(method=\"chat\", is_async=False, with_record=True)\n\n return self.with_record(self.app.chat, *args, **kwargs)\n\n # TODEP\n # Compatible with llama_index.chat_engine.types.BaseChatEngine.achat .\n async def achat_with_record(self, *args,\n **kwargs) -> Tuple[AgentChatResponse, Record]:\n assert isinstance(self.app, BaseChatEngine)\n\n self._with_dep_message(method=\"achat\", is_async=True, with_record=True)\n\n return await self.awith_record(self.app.achat, *args, **kwargs)\n\n # TODEP\n # Compatible with llama_index.chat_engine.types.BaseChatEngine.stream_chat .\n def stream_chat_with_record(\n self, *args, **kwargs\n ) -> Tuple[StreamingAgentChatResponse, Record]:\n\n assert isinstance(self.app, BaseChatEngine)\n\n self._with_dep_message(\n method=\"stream\", is_async=False, with_record=True\n )\n\n return self.with_record(self.app.stream_chat, *args, **kwargs)\n\n # TODEP\n # Compatible with llama_index.chat_engine.types.BaseChatEngine.astream_chat .\n async def astream_chat_with_record(\n self, *args, **kwargs\n ) -> Tuple[StreamingAgentChatResponse, Record]:\n\n assert isinstance(self.app, BaseChatEngine)\n\n self._with_dep_message(\n method=\"astream_chat\", is_async=True, with_record=True\n )\n\n return await self.awith_record(self.app.astream_chat, *args, **kwargs)\n
"},{"location":"trulens_eval/api/trullama/#trulens_eval.trulens_eval.tru_llama.TruLlama.main_input","title":"
main_input(func, sig, bindings)","text":"
Determine the main input string for the given function func with signature sig if it is to be called with the given bindings bindings.
Source code in
trulens_eval/trulens_eval/tru_llama.py def main_input(\n self, func: Callable, sig: Signature, bindings: BoundArguments\n) -> str:\n \"\"\"\n Determine the main input string for the given function `func` with\n signature `sig` if it is to be called with the given bindings\n `bindings`.\n \"\"\"\n\n if 'str_or_query_bundle' in bindings.arguments:\n # llama_index specific\n return bindings.arguments['str_or_query_bundle']\n\n elif 'message' in bindings.arguments:\n # llama_index specific\n return bindings.arguments['message']\n\n else:\n\n return App.main_input(self, func, sig, bindings)\n
"},{"location":"trulens_eval/api/trullama/#trulens_eval.trulens_eval.tru_llama.TruLlama.main_output","title":"
main_output(func, sig, bindings, ret)","text":"
Determine the main out string for the given function func with signature sig after it is called with the given bindings and has returned ret.
Source code in
trulens_eval/trulens_eval/tru_llama.py def main_output(\n self, func: Callable, sig: Signature, bindings: BoundArguments, ret: Any\n) -> Optional[str]:\n \"\"\"\n Determine the main out string for the given function `func` with\n signature `sig` after it is called with the given `bindings` and has\n returned `ret`.\n \"\"\"\n\n try:\n attr = self._main_output_attribute(ret)\n\n if attr is not None:\n return getattr(ret, attr)\n else: # attr is None\n return App.main_output(self, func, sig, bindings, ret)\n\n except NotImplementedError:\n return None\n
"},{"location":"trulens_eval/api/trullama/#trulens_eval.trulens_eval.tru_llama.TruLlama.select_source_nodes","title":"
select_source_nodes() classmethod","text":"
Get the path to the source nodes in the query output.
Source code in
trulens_eval/trulens_eval/tru_llama.py @classmethod\ndef select_source_nodes(cls) -> JSONPath:\n \"\"\"\n Get the path to the source nodes in the query output.\n \"\"\"\n return cls.select_outputs().source_nodes[:]\n
"},{"location":"trulens_explain/attribution_parameterization/","title":"Attributions","text":""},{"location":"trulens_explain/attribution_parameterization/#attribution-parameterization","title":"Attribution Parameterization","text":"
Attributions for different models and use cases can range from simple to more complex. This page provides guidelines on how to set various attribution parameters to achieve your LLM explainability goals.
"},{"location":"trulens_explain/attribution_parameterization/#basic-definitions-and-terminology","title":"Basic Definitions and Terminology","text":"
What is a tensor? A tensor is a multidimensional object that can be model inputs, or layer activations.
What is a layer? A layer is a set of neurons that can be thought of as a function on input tensors. Layer inputs are tensors. Layer outputs are modified tensors.
What are anchors? Anchors are ways of specifying which tensors you want. You may want the input tensor of a layer, or the output tensor of a layer.
E.g. Say you have a concat layer and you want to explain the 2 concatenated tensors. The concat operation is not usually a layer tracked by the model. If you try the 'in' anchor of the layer after the operation, you get a single tensor with all the information you need.
What is a Quantity of Interest (QoI)? A QoI is a scalar number that is being explained.
E.g. With saliency maps, you get dx/dy (i.e. the effect of input on output). y in this case is the QoI scalar. It is usually the output of a neuron, but could be a sum of multiple neurons.
What is an attribution? An attribution is a numerical value associated with every element in a tensor that explains a QoI.
E.g. With saliency maps, you get dx/dy. x is the associated tensor. The entirety of dx/dy is the explanation.
What are cuts? Cuts are tensors that cut a network into two parts. They are composed of a layer and an anchor.
What are slices? Slices are two cuts leaving a slice of the network. The attribution will be on the first cut, explaining the QoI on the second cut of the slice.
E.g. With saliency maps, the TruLens slice would be AttributionCut: Cut(x) to QoICut: Cut(y), denoted by Slice(Cut(x),Cut(y)).
"},{"location":"trulens_explain/attribution_parameterization/#how-to-use-trulens","title":"How to use TruLens?","text":"
This section will cover different use cases from the most basic to the most complex. For the following use cases, it may help to refer to Summary.
"},{"location":"trulens_explain/attribution_parameterization/#case-1-input-output-cut-basic-configuration","title":"Case 1: Input-Output cut (Basic configuration)","text":"
Use case: Explain the input given the output. Cuts needed: TruLens defaults. Attribution Cut (The tensor we would like to assign importance) \u2192 InputCut (model args / kwargs) QoI Cut (The tensor that we are interested to explain) \u2192 OutputCut
"},{"location":"trulens_explain/attribution_parameterization/#case-2-the-qoi-cut","title":"Case 2: The QoI Cut","text":"
Now suppose you want to explain some internal (intermediate) layer\u2019s output (i.e. how the input is affecting the output at some intermediate layer).
Use case: Explain something that isn't the default model output.
E.g. If you want to explain a logit layer instead of the probit (final) layer.
Cuts needed: As you want to explain something different than the default output, you need to change the QoI from the default to the layer that you are interested. Attribution Cut \u2192 InputCut QoI Cut \u2192 Your logit layer, anchor:'out'
"},{"location":"trulens_explain/attribution_parameterization/#case-3-the-attribution-cut","title":"Case 3: The Attribution Cut","text":"
Now suppose you want to know the attribution of some internal layer on the final output.
Use cases:
- As a preprocessing step, you drop a feature, so do not need attributions on that.
- For PyTorch models, model inputs are not tensors, so you'd want the 'in' anchor of the first layer.
Cuts needed: As you want to know the affect of some other layer rather than the input layer, you need to customize the attribution cut. Model inputs \u2192 InputCut Attribution Cut \u2192 Your attribution layer (The layer you want to assign importance/attributions with respect to output), anchor:'in' QoI Cut \u2192 OutputCut
"},{"location":"trulens_explain/attribution_parameterization/#advanced-use-cases","title":"Advanced Use Cases","text":"
For the following use cases, it may help to refer to Advanced Definitions.
"},{"location":"trulens_explain/attribution_parameterization/#case-4-the-distribution-of-interest-doi-cut-explanation-flexibility","title":"Case 4: The Distribution of Interest (DoI) Cut / Explanation flexibility","text":"
Usually, we explain the output with respect to each point in the input. All cases up to now were using a default called PointDoI. Now, suppose you want to explain using an aggregate over samples of points.
Use case: You want to perform approaches like Integrated Gradients, Grad-CAM, Shapley values instead of saliency maps. These only differ by sampling strategies.
E.g. Integrated Gradients is a sample from a straight line from a baseline to a value.
Cuts needed: Define a DoI that samples from the default attribution cut. Model inputs \u2192 InputCut DoI/Attribution Cut \u2192 Your baseline/DoI/attribution layer, anchor:'in' QoI Cut \u2192 OutputCut
"},{"location":"trulens_explain/attribution_parameterization/#case-5-internal-explanations","title":"Case 5: Internal explanations","text":"
Use case: You want to explain an internal layer. Methods like Integrated Gradients are a DoI on the baseline to the value, but it is located on the layer the baseline is defined. If you want to explain an internal layer, you do not move the DoI layer. Cuts needed: Attribution layer different from DoI. Model inputs \u2192 InputCut DoI Cut \u2192 Your baseline/DoI layer, anchor:'in' Attribution Cut \u2192 Your internal attribution layer, anchor:'out' or 'in' QoI Cut \u2192 OutputCut
"},{"location":"trulens_explain/attribution_parameterization/#case-6-your-baseline-happens-at-a-different-layer-than-your-sampling","title":"Case 6: Your baseline happens at a different layer than your sampling.","text":"
Use Case: in NLP, baselines are tokens, but the interpolation is on the embedding layer. Cuts needed: Baseline different from DoI. Model inputs \u2192 InputCut Baseline Cut \u2192 Tokens, anchor:'out' DoI/Attribution Cut \u2192 Embeddings, anchor:'out' QoI Cut \u2192 OutputCut
"},{"location":"trulens_explain/attribution_parameterization/#case-7-putting-it-together-the-most-complex-case-we-can-perform-with-trulens","title":"Case 7: Putting it together - The most complex case we can perform with TruLens","text":"
Use Case: Internal layer explanations of NLP, on the logit layer of a model with probit outputs. Model inputs \u2192 InputCut Baseline Cut \u2192 Tokens, anchor:'out' DoI Cut \u2192 Embeddings, anchor:'out' Attribution Cut \u2192 Internal layer, anchor:'out' QoI Cut \u2192 Logit layer, anchor:'out'
"},{"location":"trulens_explain/attribution_parameterization/#summary","title":"Summary","text":"
InputCut is model args / kwargs. OutputCut is the model output.
Baseline Cut is the tensor associated with the Integrated Gradients baseline. Can be the InputCut or later. DoI Cut is the tensor associated with explanation sampling. Can be the BaselineCut or later. Attribution Cut is the tensor that should be explained. Can be the DoICut or later. QoI Cut is what is being explained with a QoI. Must be after the AttributionCut.
"},{"location":"trulens_explain/attribution_parameterization/#advanced-definitions","title":"Advanced Definitions","text":"
What is a Distribution of Interest (DoI)?
The distribution of interest is a concept of aggregating attributions over a sample or distribution.
- Grad-CAM (Paper, GitHub, Docs) does this over a Gaussian distribution of inputs.
- Shapley values (GitHub, Docs) do this over different background data.
- Integrated Gradients (Paper, Tutorial) do this over an interpolation from a baseline to the input.
How does this relate to the Attribution Cut?
The sample or distributions are taken at a place that is humanly considered the input, even if this differs from the programmatic model input.
For attributions, all parts of a network can have an attribution towards the QoI. The most common use case is to explain the tensors that are also humanly considered the input (which is where the DoI occurs).
How does this relate to the Baseline Cut?
The Baseline Cut is only applicable to the Integrated Gradients method. It is also only needed when there is no mathematical way to interpolate the baseline to the input.
E.g. if the input is 'Hello', but the baseline is a '[MASK]' token, we cannot interpolate that. We define the baseline at the token layer, but interpolate on a numeric layer like the embeddings.
"},{"location":"trulens_explain/gh_top_intro/","title":"Gh top intro","text":""},{"location":"trulens_explain/gh_top_intro/#trulens-explain","title":"TruLens-Explain","text":"
TruLens-Explain is a cross-framework library for deep learning explainability. It provides a uniform abstraction over a number of different frameworks. It provides a uniform abstraction layer over TensorFlow, Pytorch, and Keras and allows input and internal explanations.
"},{"location":"trulens_explain/gh_top_intro/#installation-and-setup","title":"Installation and Setup","text":"
These installation instructions assume that you have conda installed and added to your path.
-
Create a virtual environment (or modify an existing one).
conda create -n \"<my_name>\" python=3 # Skip if using existing environment.\nconda activate <my_name>\n
-
Install dependencies.
conda install tensorflow-gpu=1 # Or whatever backend you're using.\nconda install keras # Or whatever backend you're using.\nconda install matplotlib # For visualizations.\n
-
[Pip installation] Install the trulens pip package from PyPI.
pip install trulens\n
"},{"location":"trulens_explain/gh_top_intro/#quick-usage","title":"Quick Usage","text":"
To quickly play around with the TruLens library, check out the following Colab notebooks:
- PyTorch:
- TensorFlow 2 / Keras:
For more information, see TruLens-Explain Documentation.
"},{"location":"trulens_explain/install/","title":"\ud83d\ude80 Installation","text":""},{"location":"trulens_explain/install/#getting-access-to-trulens","title":"Getting access to TruLens","text":"
These installation instructions assume that you have conda installed and added to your path.
-
Create a virtual environment (or modify an existing one).
conda create -n \"<my_name>\" python=3.7 # Skip if using existing environment.\nconda activate <my_name>\n
-
Install dependencies.
conda install tensorflow-gpu=1 # Or whatever backend you're using.\nconda install keras # Or whatever backend you're using.\nconda install matplotlib # For visualizations.\n
-
[Pip installation] Install the trulens pip package from PyPI.
pip install trulens\n
-
[Local installation] If you would like to develop or modify TruLens, you can download the source code by cloning the TruLens repo.
git clone https://github.com/truera/trulens.git\n
-
[Local installation] Install the TruLens repo.
cd trulens_explain\npip install -e .\n
"},{"location":"trulens_explain/quickstart/","title":"\u26a1 Quickstart","text":""},{"location":"trulens_explain/quickstart/#quickstart","title":"Quickstart","text":""},{"location":"trulens_explain/quickstart/#playground","title":"Playground","text":"
To quickly play around with the TruLens library, check out the following Colab notebooks:
- PyTorch:
- TensorFlow 2 / Keras:
"},{"location":"trulens_explain/quickstart/#install-use","title":"Install & Use","text":"
Check out the Installation instructions for information on how to install the library, use it, and contribute.
"},{"location":"trulens_explain/api/attribution/","title":"Attribution Methods","text":"
Attribution methods quantitatively measure the contribution of each of a function's individual inputs to its output. Gradient-based attribution methods compute the gradient of a model with respect to its inputs to describe how important each input is towards the output prediction. These methods can be applied to assist in explaining deep networks.
TruLens provides implementations of several such techniques, found in this package.
"},{"location":"trulens_explain/api/attribution/#trulens_explain.trulens.nn.attribution.AttributionMethod","title":"
AttributionMethod","text":"
Bases: ABC
Interface used by all attribution methods.
An attribution method takes a neural network model and provides the ability to assign values to the variables of the network that specify the importance of each variable towards particular predictions.
Source code in
trulens_explain/trulens/nn/attribution.py class AttributionMethod(AbstractBaseClass):\n \"\"\"\n Interface used by all attribution methods.\n\n An attribution method takes a neural network model and provides the ability\n to assign values to the variables of the network that specify the importance\n of each variable towards particular predictions.\n \"\"\"\n\n @abstractmethod\n def __init__(\n self, model: ModelWrapper, rebatch_size: int = None, *args, **kwargs\n ):\n \"\"\"\n Abstract constructor.\n\n Parameters:\n model: ModelWrapper\n Model for which attributions are calculated.\n\n rebatch_size: int (optional)\n Will rebatch instances to this size if given. This may be\n required for GPU usage if using a DoI which produces multiple\n instances per user-provided instance. Many valued DoIs will\n expand the tensors sent to each layer to original_batch_size *\n doi_size. The rebatch size will break up original_batch_size *\n doi_size into rebatch_size chunks to send to model.\n \"\"\"\n self._model = model\n\n self.rebatch_size = rebatch_size\n\n @property\n def model(self) -> ModelWrapper:\n \"\"\"\n Model for which attributions are calculated.\n \"\"\"\n return self._model\n\n @abstractmethod\n def _attributions(self, model_inputs: ModelInputs) -> AttributionResult:\n \"\"\"\n For attributions that have options to return multiple things depending\n on configuration, wrap those multiple things in the AttributionResult\n tuple.\n \"\"\"\n ...\n\n def attributions(\n self, *model_args: ArgsLike, **model_kwargs: KwargsLike\n ) -> Union[TensorLike, ArgsLike[TensorLike],\n ArgsLike[ArgsLike[TensorLike]]]:\n \"\"\"\n Returns attributions for the given input. Attributions are in the same\n shape as the layer that attributions are being generated for. \n\n The numeric scale of the attributions will depend on the specific\n implementations of the Distribution of Interest and Quantity of\n Interest. However it is generally related to the scale of gradients on\n the Quantity of Interest. \n\n For example, Integrated Gradients uses the linear interpolation\n Distribution of Interest which subsumes the completeness axiom which\n ensures the sum of all attributions of a record equals the output\n determined by the Quantity of Interest on the same record. \n\n The Point Distribution of Interest will be determined by the gradient at\n a single point, thus being a good measure of model sensitivity. \n\n Parameters:\n model_args: ArgsLike, model_kwargs: KwargsLike\n The args and kwargs given to the call method of a model. This\n should represent the records to obtain attributions for, assumed\n to be a *batched* input. if `self.model` supports evaluation on\n *data tensors*, the appropriate tensor type may be used (e.g.,\n Pytorch models may accept Pytorch tensors in addition to\n `np.ndarray`s). The shape of the inputs must match the input\n shape of `self.model`. \n\n Returns\n - np.ndarray when single attribution_cut input, single qoi output\n - or ArgsLike[np.ndarray] when single input, multiple output (or\n vice versa) \n - or ArgsLike[ArgsLike[np.ndarray]] when multiple output (outer),\n multiple input (inner)\n\n An array of attributions, matching the shape and type of `from_cut`\n of the slice. Each entry in the returned array represents the degree\n to which the corresponding feature affected the model's outcome on\n the corresponding point.\n\n If attributing to a component with multiple inputs, a list for each\n will be returned.\n\n If the quantity of interest features multiple outputs, a list for\n each will be returned.\n \"\"\"\n\n # Calls like: attributions([arg1, arg2]) will get read as model_args =\n # ([arg1, arg2],), that is, a tuple with a single element containing the\n # model args. Test below checks for this. TODO: Disallow such\n # invocations? They should be given as attributions(arg1, arg2).\n if isinstance(model_args,\n tuple) and len(model_args) == 1 and isinstance(\n model_args[0], DATA_CONTAINER_TYPE):\n model_args = model_args[0]\n\n model_inputs = ModelInputs(\n args=many_of_om(model_args), kwargs=model_kwargs\n )\n # Will cast results to this data container type.\n return_type = type(model_inputs.first_batchable(get_backend()))\n\n pieces = self._attributions(model_inputs)\n\n # Format attributions into the public structure which throws out output\n # lists and input lists if there is only one output or only one input.\n # Also cast to whatever the input type was.\n attributions: Outputs[Inputs[np.ndarray]] = nested_cast(\n backend=get_backend(), astype=return_type, args=pieces.attributions\n )\n attributions: Outputs[OM[Inputs, np.ndarray]\n ] = [om_of_many(attr) for attr in attributions]\n attributions: OM[Outputs, OM[Inputs,\n np.ndarray]] = om_of_many(attributions)\n\n if pieces.gradients is not None or pieces.interventions is not None:\n tru_logger.warning(\n \"AttributionMethod configured to return gradients or interventions. \"\n \"Use the internal _attribution call to retrieve those.\"\n )\n\n return attributions\n
"},{"location":"trulens_explain/api/attribution/#trulens_explain.trulens.nn.attribution.AttributionMethod.model","title":"
model: ModelWrapper property","text":"
Model for which attributions are calculated.
"},{"location":"trulens_explain/api/attribution/#trulens_explain.trulens.nn.attribution.AttributionMethod.__init__","title":"
__init__(model, rebatch_size=None, *args, **kwargs) abstractmethod","text":"
Abstract constructor.
Parameters:
Name Type Description Default
model ModelWrapper ModelWrapper Model for which attributions are calculated.
required
rebatch_size int int (optional) Will rebatch instances to this size if given. This may be required for GPU usage if using a DoI which produces multiple instances per user-provided instance. Many valued DoIs will expand the tensors sent to each layer to original_batch_size * doi_size. The rebatch size will break up original_batch_size * doi_size into rebatch_size chunks to send to model.
None Source code in
trulens_explain/trulens/nn/attribution.py @abstractmethod\ndef __init__(\n self, model: ModelWrapper, rebatch_size: int = None, *args, **kwargs\n):\n \"\"\"\n Abstract constructor.\n\n Parameters:\n model: ModelWrapper\n Model for which attributions are calculated.\n\n rebatch_size: int (optional)\n Will rebatch instances to this size if given. This may be\n required for GPU usage if using a DoI which produces multiple\n instances per user-provided instance. Many valued DoIs will\n expand the tensors sent to each layer to original_batch_size *\n doi_size. The rebatch size will break up original_batch_size *\n doi_size into rebatch_size chunks to send to model.\n \"\"\"\n self._model = model\n\n self.rebatch_size = rebatch_size\n
"},{"location":"trulens_explain/api/attribution/#trulens_explain.trulens.nn.attribution.AttributionMethod.attributions","title":"
attributions(*model_args, **model_kwargs)","text":"
Returns attributions for the given input. Attributions are in the same shape as the layer that attributions are being generated for.
The numeric scale of the attributions will depend on the specific implementations of the Distribution of Interest and Quantity of Interest. However it is generally related to the scale of gradients on the Quantity of Interest.
For example, Integrated Gradients uses the linear interpolation Distribution of Interest which subsumes the completeness axiom which ensures the sum of all attributions of a record equals the output determined by the Quantity of Interest on the same record.
The Point Distribution of Interest will be determined by the gradient at a single point, thus being a good measure of model sensitivity.
Parameters:
Name Type Description Default
model_args ArgsLike ArgsLike, model_kwargs: KwargsLike The args and kwargs given to the call method of a model. This should represent the records to obtain attributions for, assumed to be a batched input. if self.model supports evaluation on data tensors, the appropriate tensor type may be used (e.g., Pytorch models may accept Pytorch tensors in addition to np.ndarrays). The shape of the inputs must match the input shape of self.model.
() Returns - np.ndarray when single attribution_cut input, single qoi output - or ArgsLike[np.ndarray] when single input, multiple output (or vice versa) - or ArgsLike[ArgsLike[np.ndarray]] when multiple output (outer), multiple input (inner)
An array of attributions, matching the shape and type of `from_cut`\nof the slice. Each entry in the returned array represents the degree\nto which the corresponding feature affected the model's outcome on\nthe corresponding point.\n\nIf attributing to a component with multiple inputs, a list for each\nwill be returned.\n\nIf the quantity of interest features multiple outputs, a list for\neach will be returned.\n
Source code in
trulens_explain/trulens/nn/attribution.py def attributions(\n self, *model_args: ArgsLike, **model_kwargs: KwargsLike\n) -> Union[TensorLike, ArgsLike[TensorLike],\n ArgsLike[ArgsLike[TensorLike]]]:\n \"\"\"\n Returns attributions for the given input. Attributions are in the same\n shape as the layer that attributions are being generated for. \n\n The numeric scale of the attributions will depend on the specific\n implementations of the Distribution of Interest and Quantity of\n Interest. However it is generally related to the scale of gradients on\n the Quantity of Interest. \n\n For example, Integrated Gradients uses the linear interpolation\n Distribution of Interest which subsumes the completeness axiom which\n ensures the sum of all attributions of a record equals the output\n determined by the Quantity of Interest on the same record. \n\n The Point Distribution of Interest will be determined by the gradient at\n a single point, thus being a good measure of model sensitivity. \n\n Parameters:\n model_args: ArgsLike, model_kwargs: KwargsLike\n The args and kwargs given to the call method of a model. This\n should represent the records to obtain attributions for, assumed\n to be a *batched* input. if `self.model` supports evaluation on\n *data tensors*, the appropriate tensor type may be used (e.g.,\n Pytorch models may accept Pytorch tensors in addition to\n `np.ndarray`s). The shape of the inputs must match the input\n shape of `self.model`. \n\n Returns\n - np.ndarray when single attribution_cut input, single qoi output\n - or ArgsLike[np.ndarray] when single input, multiple output (or\n vice versa) \n - or ArgsLike[ArgsLike[np.ndarray]] when multiple output (outer),\n multiple input (inner)\n\n An array of attributions, matching the shape and type of `from_cut`\n of the slice. Each entry in the returned array represents the degree\n to which the corresponding feature affected the model's outcome on\n the corresponding point.\n\n If attributing to a component with multiple inputs, a list for each\n will be returned.\n\n If the quantity of interest features multiple outputs, a list for\n each will be returned.\n \"\"\"\n\n # Calls like: attributions([arg1, arg2]) will get read as model_args =\n # ([arg1, arg2],), that is, a tuple with a single element containing the\n # model args. Test below checks for this. TODO: Disallow such\n # invocations? They should be given as attributions(arg1, arg2).\n if isinstance(model_args,\n tuple) and len(model_args) == 1 and isinstance(\n model_args[0], DATA_CONTAINER_TYPE):\n model_args = model_args[0]\n\n model_inputs = ModelInputs(\n args=many_of_om(model_args), kwargs=model_kwargs\n )\n # Will cast results to this data container type.\n return_type = type(model_inputs.first_batchable(get_backend()))\n\n pieces = self._attributions(model_inputs)\n\n # Format attributions into the public structure which throws out output\n # lists and input lists if there is only one output or only one input.\n # Also cast to whatever the input type was.\n attributions: Outputs[Inputs[np.ndarray]] = nested_cast(\n backend=get_backend(), astype=return_type, args=pieces.attributions\n )\n attributions: Outputs[OM[Inputs, np.ndarray]\n ] = [om_of_many(attr) for attr in attributions]\n attributions: OM[Outputs, OM[Inputs,\n np.ndarray]] = om_of_many(attributions)\n\n if pieces.gradients is not None or pieces.interventions is not None:\n tru_logger.warning(\n \"AttributionMethod configured to return gradients or interventions. \"\n \"Use the internal _attribution call to retrieve those.\"\n )\n\n return attributions\n
"},{"location":"trulens_explain/api/attribution/#trulens_explain.trulens.nn.attribution.AttributionResult","title":"
AttributionResult dataclass","text":"
_attribution method output container.
Source code in
trulens_explain/trulens/nn/attribution.py @dataclass\nclass AttributionResult:\n \"\"\"\n _attribution method output container.\n \"\"\"\n\n attributions: Outputs[Inputs[TensorLike]] = None\n gradients: Outputs[Inputs[Uniform[TensorLike]]] = None\n interventions: Inputs[Uniform[TensorLike]] = None\n
"},{"location":"trulens_explain/api/attribution/#trulens_explain.trulens.nn.attribution.InputAttribution","title":"
InputAttribution","text":"
Bases: InternalInfluence
Attributions of input features on either internal or output quantities. This is essentially an alias for
InternalInfluence(\n model,\n (trulens.nn.slices.InputCut(), cut),\n qoi,\n doi,\n multiply_activation)\n
Source code in
trulens_explain/trulens/nn/attribution.py class InputAttribution(InternalInfluence):\n \"\"\"\n Attributions of input features on either internal or output quantities. This\n is essentially an alias for\n\n ```python\n InternalInfluence(\n model,\n (trulens.nn.slices.InputCut(), cut),\n qoi,\n doi,\n multiply_activation)\n ```\n \"\"\"\n\n def __init__(\n self,\n model: ModelWrapper,\n qoi_cut: CutLike = None, # see WARNING-LOAD-INIT\n qoi: QoiLike = 'max',\n doi_cut: CutLike = None, # see WARNING-LOAD-INIT\n doi: DoiLike = 'point',\n multiply_activation: bool = True,\n *args,\n **kwargs\n ):\n \"\"\"\n Parameters:\n model :\n Model for which attributions are calculated.\n\n qoi_cut :\n The cut determining the layer from which the QoI is derived.\n Expects a `Cut` object, or a related type that can be\n interpreted as a `Cut`, as documented below.\n\n If an `int` is given, it represents the index of a layer in\n `model`. \n\n If a `str` is given, it represents the name of a layer in\n `model`. \n\n `None` is an alternative for `slices.OutputCut()`.\n\n qoi : quantities.QoI | int | tuple | str\n Quantity of interest to attribute. Expects a `QoI` object, or a\n related type that can be interpreted as a `QoI`, as documented\n below.\n\n If an `int` is given, the quantity of interest is taken to be\n the slice output for the class/neuron/channel specified by the\n given integer, i.e., ```python\n quantities.InternalChannelQoI(qoi) ```\n\n If a tuple or list of two integers is given, then the quantity\n of interest is taken to be the comparative quantity for the\n class given by the first integer against the class given by the\n second integer, i.e., ```python quantities.ComparativeQoI(*qoi)\n ```\n\n If a callable is given, it is interpreted as a function\n representing the QoI, i.e., ```python quantities.LambdaQoI(qoi)\n ```\n\n If the string, `'max'`, is given, the quantity of interest is\n taken to be the output for the class with the maximum score,\n i.e., ```python quantities.MaxClassQoI() ```\n\n doi_cut :\n For models which have non-differentiable pre-processing at the\n start of the model, specify the cut of the initial\n differentiable input form. For NLP models, for example, this\n could point to the embedding layer. If not provided, InputCut is\n assumed.\n\n doi : distributions.DoI | str\n Distribution of interest over inputs. Expects a `DoI` object, or\n a related type that can be interpreted as a `DoI`, as documented\n below.\n\n If the string, `'point'`, is given, the distribution is taken to\n be the single point passed to `attributions`, i.e., ```python\n distributions.PointDoi() ```\n\n If the string, `'linear'`, is given, the distribution is taken\n to be the linear interpolation from the zero input to the point\n passed to `attributions`, i.e., ```python\n distributions.LinearDoi() ```\n\n multiply_activation : bool, optional\n Whether to multiply the gradient result by its corresponding\n activation, thus converting from \"*influence space*\" to\n \"*attribution space*.\"\n \"\"\"\n if doi_cut is None:\n # WARNING-LOAD-INIT: Do not put this as a default arg in the def\n # line. That would cause an instantiation of InputCut when this\n # class is loaded and before it is used. Because get_backend gets\n # called in Cut.__init__, it may fail if this class is loaded before\n # trulens.nn.models.get_model_wrapper is called on some model.\n doi_cut = InputCut()\n\n super().__init__(\n model, (doi_cut, qoi_cut),\n qoi,\n doi,\n multiply_activation=multiply_activation,\n *args,\n **kwargs\n )\n
"},{"location":"trulens_explain/api/attribution/#trulens_explain.trulens.nn.attribution.InputAttribution.__init__","title":"
__init__(model, qoi_cut=None, qoi='max', doi_cut=None, doi='point', multiply_activation=True, *args, **kwargs)","text":"
Parameters:
Name Type Description Default
model Model for which attributions are calculated.
required
qoi_cut The cut determining the layer from which the QoI is derived. Expects a Cut object, or a related type that can be interpreted as a Cut, as documented below.
If an int is given, it represents the index of a layer in model.
If a str is given, it represents the name of a layer in model.
None is an alternative for slices.OutputCut().
None qoi quantities.QoI | int | tuple | str Quantity of interest to attribute. Expects a QoI object, or a related type that can be interpreted as a QoI, as documented below.
If an int is given, the quantity of interest is taken to be the slice output for the class/neuron/channel specified by the given integer, i.e., python quantities.InternalChannelQoI(qoi)
If a tuple or list of two integers is given, then the quantity of interest is taken to be the comparative quantity for the class given by the first integer against the class given by the second integer, i.e., ```python quantities.ComparativeQoI(*qoi)
If a callable is given, it is interpreted as a function\nrepresenting the QoI, i.e., ```python quantities.LambdaQoI(qoi)\n
If the string, 'max', is given, the quantity of interest is taken to be the output for the class with the maximum score, i.e., python quantities.MaxClassQoI()
'max' doi_cut For models which have non-differentiable pre-processing at the start of the model, specify the cut of the initial differentiable input form. For NLP models, for example, this could point to the embedding layer. If not provided, InputCut is assumed.
None doi distributions.DoI | str Distribution of interest over inputs. Expects a DoI object, or a related type that can be interpreted as a DoI, as documented below.
If the string, 'point', is given, the distribution is taken to be the single point passed to attributions, i.e., python distributions.PointDoi()
If the string, 'linear', is given, the distribution is taken to be the linear interpolation from the zero input to the point passed to attributions, i.e., python distributions.LinearDoi()
'point' multiply_activation bool, optional Whether to multiply the gradient result by its corresponding activation, thus converting from \"influence space\" to \"attribution space.\"
True Source code in
trulens_explain/trulens/nn/attribution.py def __init__(\n self,\n model: ModelWrapper,\n qoi_cut: CutLike = None, # see WARNING-LOAD-INIT\n qoi: QoiLike = 'max',\n doi_cut: CutLike = None, # see WARNING-LOAD-INIT\n doi: DoiLike = 'point',\n multiply_activation: bool = True,\n *args,\n **kwargs\n):\n \"\"\"\n Parameters:\n model :\n Model for which attributions are calculated.\n\n qoi_cut :\n The cut determining the layer from which the QoI is derived.\n Expects a `Cut` object, or a related type that can be\n interpreted as a `Cut`, as documented below.\n\n If an `int` is given, it represents the index of a layer in\n `model`. \n\n If a `str` is given, it represents the name of a layer in\n `model`. \n\n `None` is an alternative for `slices.OutputCut()`.\n\n qoi : quantities.QoI | int | tuple | str\n Quantity of interest to attribute. Expects a `QoI` object, or a\n related type that can be interpreted as a `QoI`, as documented\n below.\n\n If an `int` is given, the quantity of interest is taken to be\n the slice output for the class/neuron/channel specified by the\n given integer, i.e., ```python\n quantities.InternalChannelQoI(qoi) ```\n\n If a tuple or list of two integers is given, then the quantity\n of interest is taken to be the comparative quantity for the\n class given by the first integer against the class given by the\n second integer, i.e., ```python quantities.ComparativeQoI(*qoi)\n ```\n\n If a callable is given, it is interpreted as a function\n representing the QoI, i.e., ```python quantities.LambdaQoI(qoi)\n ```\n\n If the string, `'max'`, is given, the quantity of interest is\n taken to be the output for the class with the maximum score,\n i.e., ```python quantities.MaxClassQoI() ```\n\n doi_cut :\n For models which have non-differentiable pre-processing at the\n start of the model, specify the cut of the initial\n differentiable input form. For NLP models, for example, this\n could point to the embedding layer. If not provided, InputCut is\n assumed.\n\n doi : distributions.DoI | str\n Distribution of interest over inputs. Expects a `DoI` object, or\n a related type that can be interpreted as a `DoI`, as documented\n below.\n\n If the string, `'point'`, is given, the distribution is taken to\n be the single point passed to `attributions`, i.e., ```python\n distributions.PointDoi() ```\n\n If the string, `'linear'`, is given, the distribution is taken\n to be the linear interpolation from the zero input to the point\n passed to `attributions`, i.e., ```python\n distributions.LinearDoi() ```\n\n multiply_activation : bool, optional\n Whether to multiply the gradient result by its corresponding\n activation, thus converting from \"*influence space*\" to\n \"*attribution space*.\"\n \"\"\"\n if doi_cut is None:\n # WARNING-LOAD-INIT: Do not put this as a default arg in the def\n # line. That would cause an instantiation of InputCut when this\n # class is loaded and before it is used. Because get_backend gets\n # called in Cut.__init__, it may fail if this class is loaded before\n # trulens.nn.models.get_model_wrapper is called on some model.\n doi_cut = InputCut()\n\n super().__init__(\n model, (doi_cut, qoi_cut),\n qoi,\n doi,\n multiply_activation=multiply_activation,\n *args,\n **kwargs\n )\n
"},{"location":"trulens_explain/api/attribution/#trulens_explain.trulens.nn.attribution.IntegratedGradients","title":"
IntegratedGradients","text":"
Bases: InputAttribution
Implementation for the Integrated Gradients method from the following paper:
Axiomatic Attribution for Deep Networks
This should be cited using:
@INPROCEEDINGS{\n sundararajan17axiomatic,\n author={Mukund Sundararajan and Ankur Taly, and Qiqi Yan},\n title={Axiomatic Attribution for Deep Networks},\n booktitle={International Conference on Machine Learning (ICML)},\n year={2017},\n}\n
This is essentially an alias for
InternalInfluence(\n model,\n (trulens.nn.slices.InputCut(), trulens.nn.slices.OutputCut()),\n 'max',\n trulens.nn.distributions.LinearDoi(baseline, resolution),\n multiply_activation=True)\n
Source code in
trulens_explain/trulens/nn/attribution.py class IntegratedGradients(InputAttribution):\n \"\"\"\n Implementation for the Integrated Gradients method from the following paper:\n\n [Axiomatic Attribution for Deep Networks](\n https://arxiv.org/pdf/1703.01365)\n\n This should be cited using:\n\n ```bibtex\n @INPROCEEDINGS{\n sundararajan17axiomatic,\n author={Mukund Sundararajan and Ankur Taly, and Qiqi Yan},\n title={Axiomatic Attribution for Deep Networks},\n booktitle={International Conference on Machine Learning (ICML)},\n year={2017},\n }\n ```\n\n This is essentially an alias for\n\n ```python\n InternalInfluence(\n model,\n (trulens.nn.slices.InputCut(), trulens.nn.slices.OutputCut()),\n 'max',\n trulens.nn.distributions.LinearDoi(baseline, resolution),\n multiply_activation=True)\n ```\n \"\"\"\n\n def __init__(\n self,\n model: ModelWrapper,\n baseline=None,\n resolution: int = 50,\n doi_cut=None, # see WARNING-LOAD-INIT\n qoi='max',\n qoi_cut=None, # see WARNING-LOAD-INIT\n *args,\n **kwargs\n ):\n \"\"\"\n Parameters:\n model:\n Model for which attributions are calculated.\n\n baseline:\n The baseline to interpolate from. Must be same shape as the \n input. If `None` is given, the zero vector in the appropriate \n shape will be used.\n\n resolution:\n Number of points to use in the approximation. A higher \n resolution is more computationally expensive, but gives a better\n approximation of the mathematical formula this attribution \n method represents.\n \"\"\"\n\n if doi_cut is None:\n doi_cut = InputCut()\n\n if qoi_cut is None:\n qoi_cut = OutputCut()\n\n super().__init__(\n model=model,\n qoi_cut=qoi_cut,\n qoi=qoi,\n doi_cut=doi_cut,\n doi=LinearDoi(baseline, resolution, cut=doi_cut),\n multiply_activation=True,\n *args,\n **kwargs\n )\n
"},{"location":"trulens_explain/api/attribution/#trulens_explain.trulens.nn.attribution.IntegratedGradients.__init__","title":"
__init__(model, baseline=None, resolution=50, doi_cut=None, qoi='max', qoi_cut=None, *args, **kwargs)","text":"
Parameters:
Name Type Description Default
model ModelWrapper Model for which attributions are calculated.
required
baseline The baseline to interpolate from. Must be same shape as the input. If None is given, the zero vector in the appropriate shape will be used.
None resolution int Number of points to use in the approximation. A higher resolution is more computationally expensive, but gives a better approximation of the mathematical formula this attribution method represents.
50 Source code in
trulens_explain/trulens/nn/attribution.py def __init__(\n self,\n model: ModelWrapper,\n baseline=None,\n resolution: int = 50,\n doi_cut=None, # see WARNING-LOAD-INIT\n qoi='max',\n qoi_cut=None, # see WARNING-LOAD-INIT\n *args,\n **kwargs\n):\n \"\"\"\n Parameters:\n model:\n Model for which attributions are calculated.\n\n baseline:\n The baseline to interpolate from. Must be same shape as the \n input. If `None` is given, the zero vector in the appropriate \n shape will be used.\n\n resolution:\n Number of points to use in the approximation. A higher \n resolution is more computationally expensive, but gives a better\n approximation of the mathematical formula this attribution \n method represents.\n \"\"\"\n\n if doi_cut is None:\n doi_cut = InputCut()\n\n if qoi_cut is None:\n qoi_cut = OutputCut()\n\n super().__init__(\n model=model,\n qoi_cut=qoi_cut,\n qoi=qoi,\n doi_cut=doi_cut,\n doi=LinearDoi(baseline, resolution, cut=doi_cut),\n multiply_activation=True,\n *args,\n **kwargs\n )\n
"},{"location":"trulens_explain/api/attribution/#trulens_explain.trulens.nn.attribution.InternalInfluence","title":"
InternalInfluence","text":"
Bases: AttributionMethod
Internal attributions parameterized by a slice, quantity of interest, and distribution of interest.
The slice specifies the layers at which the internals of the model are to be exposed; it is represented by two cuts, which specify the layer the attributions are assigned to and the layer from which the quantity of interest is derived. The Quantity of Interest (QoI) is a function of the output specified by the slice that determines the network output behavior that the attributions are to describe. The Distribution of Interest (DoI) specifies the records over which the attributions are aggregated.
More information can be found in the following paper:
Influence-Directed Explanations for Deep Convolutional Networks
This should be cited using:
@INPROCEEDINGS{\n leino18influence,\n author={\n Klas Leino and\n Shayak Sen and\n Anupam Datta and\n Matt Fredrikson and\n Linyi Li},\n title={\n Influence-Directed Explanations\n for Deep Convolutional Networks},\n booktitle={IEEE International Test Conference (ITC)},\n year={2018},\n}\n
Source code in
trulens_explain/trulens/nn/attribution.py class InternalInfluence(AttributionMethod):\n \"\"\"Internal attributions parameterized by a slice, quantity of interest, and\n distribution of interest.\n\n The *slice* specifies the layers at which the internals of the model are to\n be exposed; it is represented by two *cuts*, which specify the layer the\n attributions are assigned to and the layer from which the quantity of\n interest is derived. The *Quantity of Interest* (QoI) is a function of the\n output specified by the slice that determines the network output behavior\n that the attributions are to describe. The *Distribution of Interest* (DoI)\n specifies the records over which the attributions are aggregated.\n\n More information can be found in the following paper:\n\n [Influence-Directed Explanations for Deep Convolutional Networks](\n https://arxiv.org/pdf/1802.03788.pdf)\n\n This should be cited using:\n\n ```bibtex\n @INPROCEEDINGS{\n leino18influence,\n author={\n Klas Leino and\n Shayak Sen and\n Anupam Datta and\n Matt Fredrikson and\n Linyi Li},\n title={\n Influence-Directed Explanations\n for Deep Convolutional Networks},\n booktitle={IEEE International Test Conference (ITC)},\n year={2018},\n }\n ```\n \"\"\"\n\n def __init__(\n self,\n model: ModelWrapper,\n cuts: SliceLike,\n qoi: QoiLike,\n doi: DoiLike,\n multiply_activation: bool = True,\n return_grads: bool = False,\n return_doi: bool = False,\n *args,\n **kwargs\n ):\n \"\"\"\n Parameters:\n model:\n Model for which attributions are calculated.\n\n cuts: \n The slice to use when computing the attributions. The slice \n keeps track of the layer whose output attributions are \n calculated and the layer for which the quantity of interest is \n computed. Expects a `Slice` object, or a related type that can\n be interpreted as a `Slice`, as documented below.\n\n If a single `Cut` object is given, it is assumed to be the cut \n representing the layer for which attributions are calculated \n (i.e., `from_cut` in `Slice`) and the layer for the quantity of \n interest (i.e., `to_cut` in `slices.Slice`) is taken to be the \n output of the network. If a tuple or list of two `Cut`s is \n given, they are assumed to be `from_cut` and `to_cut`, \n respectively.\n\n A cut (or the cuts within the tuple) can also be represented as \n an `int`, `str`, or `None`. If an `int` is given, it represents \n the index of a layer in `model`. If a `str` is given, it \n represents the name of a layer in `model`. `None` is an \n alternative for `slices.InputCut`.\n\n qoi:\n Quantity of interest to attribute. Expects a `QoI` object, or a\n related type that can be interpreted as a `QoI`, as documented\n below.\n\n If an `int` is given, the quantity of interest is taken to be \n the slice output for the class/neuron/channel specified by the \n given integer, i.e., \n ```python\n quantities.InternalChannelQoI(qoi)\n ```\n\n If a tuple or list of two integers is given, then the quantity \n of interest is taken to be the comparative quantity for the \n class given by the first integer against the class given by the \n second integer, i.e., \n ```python\n quantities.ComparativeQoI(*qoi)\n ```\n\n If a callable is given, it is interpreted as a function\n representing the QoI, i.e.,\n ```python\n quantities.LambdaQoI(qoi)\n ```\n\n If the string, `'max'`, is given, the quantity of interest is \n taken to be the output for the class with the maximum score, \n i.e., \n ```python\n quantities.MaxClassQoI()\n ```\n\n doi:\n Distribution of interest over inputs. Expects a `DoI` object, or\n a related type that can be interpreted as a `DoI`, as documented\n below.\n\n If the string, `'point'`, is given, the distribution is taken to\n be the single point passed to `attributions`, i.e., \n ```python\n distributions.PointDoi()\n ```\n\n If the string, `'linear'`, is given, the distribution is taken \n to be the linear interpolation from the zero input to the point \n passed to `attributions`, i.e., \n ```python\n distributions.LinearDoi()\n ```\n\n multiply_activation:\n Whether to multiply the gradient result by its corresponding\n activation, thus converting from \"*influence space*\" to \n \"*attribution space*.\"\n \"\"\"\n super().__init__(model, *args, **kwargs)\n\n self.slice = InternalInfluence.__get_slice(cuts)\n self.qoi = InternalInfluence.__get_qoi(qoi)\n self.doi = InternalInfluence.__get_doi(doi, cut=self.slice.from_cut)\n self._do_multiply = multiply_activation\n self._return_grads = return_grads\n self._return_doi = return_doi\n\n def _attributions(self, model_inputs: ModelInputs) -> AttributionResult:\n # NOTE: not symbolic\n\n B = get_backend()\n results = AttributionResult()\n\n # Create a message for out-of-memory errors regarding float and batch size.\n first_batchable = model_inputs.first_batchable(B)\n if first_batchable is None:\n batch_size = 1\n else:\n batch_size = first_batchable.shape[0]\n\n param_msgs = [\n f\"float size = {B.floatX_size} ({B.floatX}); consider changing to a smaller type.\",\n f\"batch size = {batch_size}; consider reducing the size of the batch you send to the attributions method.\"\n ]\n\n doi_cut = self.doi.cut() if self.doi.cut() else InputCut()\n\n with memory_suggestions(*param_msgs): # Handles out-of-memory messages.\n doi_val: List[B.Tensor] = self.model._fprop(\n model_inputs=model_inputs,\n to_cut=doi_cut,\n doi_cut=InputCut(),\n attribution_cut=None, # InputCut(),\n intervention=model_inputs\n )[0]\n\n doi_val = nested_map(doi_val, B.as_array)\n\n D = self.doi._wrap_public_call(doi_val, model_inputs=model_inputs)\n\n if self._return_doi:\n results.interventions = D # : Inputs[Uniform[TensorLike]]\n\n D_tensors = D[0]\n n_doi = len(D_tensors)\n if isinstance(D_tensors, MAP_CONTAINER_TYPE):\n for k in D_tensors.keys():\n if isinstance(D_tensors[k], DATA_CONTAINER_TYPE):\n n_doi = len(D_tensors[k])\n D = self.__concatenate_doi(D)\n rebatch_size = self.rebatch_size\n if rebatch_size is None:\n rebatch_size = len(D[0])\n\n intervention = TensorArgs(args=D)\n model_inputs_expanded = tile(what=model_inputs, onto=intervention)\n # Create a message for out-of-memory errors regarding doi_size.\n # TODO: Generalize this message to doi other than LinearDoI:\n doi_size_msg = f\"distribution of interest size = {n_doi}; consider reducing intervention resolution.\"\n\n combined_batch_size = n_doi * batch_size\n combined_batch_msg = f\"combined batch size = {combined_batch_size}; consider reducing batch size, intervention size\"\n\n rebatch_size_msg = f\"rebatch_size = {rebatch_size}; consider reducing this AttributionMethod constructor parameter (default is same as combined batch size).\"\n\n # Calculate the gradient of each of the points in the DoI.\n with memory_suggestions(\n param_msgs +\n [doi_size_msg, combined_batch_msg, rebatch_size_msg]\n ): # Handles out-of-memory messages.\n qoi_grads_expanded: List[Outputs[Inputs[TensorLike]]] = []\n\n for inputs_batch, intervention_batch in rebatch(\n model_inputs_expanded, intervention,\n batch_size=rebatch_size):\n\n qoi_grads_expanded_batch: Outputs[\n Inputs[TensorLike]] = self.model._qoi_bprop(\n qoi=self.qoi,\n model_inputs=inputs_batch,\n attribution_cut=self.slice.from_cut,\n to_cut=self.slice.to_cut,\n intervention=intervention_batch,\n doi_cut=doi_cut\n )\n\n # important to cast to numpy inside loop:\n qoi_grads_expanded.append(\n nested_map(qoi_grads_expanded_batch, B.as_array)\n )\n\n num_outputs = len(qoi_grads_expanded[0])\n num_inputs = len(qoi_grads_expanded[0][0])\n transpose = [\n [[] for _ in range(num_inputs)] for _ in range(num_outputs)\n ]\n for o in range(num_outputs):\n for i in range(num_inputs):\n for qoi_grads_batch in qoi_grads_expanded:\n transpose[o][i].append(qoi_grads_batch[o][i])\n\n def container_concat(x):\n \"\"\"Applies np concatenate on a container. If it is a map type, it will apply it on each key.\n\n Args:\n x (map or data container): A container of tensors\n\n Returns:\n concatenated tensors of the container.\n \"\"\"\n if isinstance(x[0], MAP_CONTAINER_TYPE):\n ret_map = {}\n for k in x[0].keys():\n ret_map[k] = np.concatenate([_dict[k] for _dict in x])\n return ret_map\n else:\n return np.concatenate(x)\n\n qoi_grads_expanded: Outputs[Inputs[np.ndarray]] = nested_map(\n transpose, container_concat, nest=2\n )\n qoi_grads_expanded: Outputs[Inputs[np.ndarray]] = nested_map(\n qoi_grads_expanded,\n lambda grad: np.reshape(grad, (n_doi, -1) + grad.shape[1:]),\n nest=2\n )\n if self._return_grads:\n results.gradients = qoi_grads_expanded # : Outputs[Inputs[Uniform[TensorLike]]]\n\n # TODO: Does this need to be done in numpy?\n attrs: Outputs[Inputs[TensorLike]] = nested_map(\n qoi_grads_expanded, lambda grad: np.mean(grad, axis=0), nest=2\n )\n\n # Multiply by the activation multiplier if specified.\n if self._do_multiply:\n with memory_suggestions(param_msgs):\n z_val = self.model._fprop(\n model_inputs=model_inputs,\n doi_cut=InputCut(),\n attribution_cut=None,\n to_cut=self.slice.from_cut,\n intervention=model_inputs # intentional\n )[0]\n\n mults: Inputs[TensorLike\n ] = self.doi._wrap_public_get_activation_multiplier(\n z_val, model_inputs=model_inputs\n )\n mults: Inputs[np.ndarray] = nested_cast(\n backend=B, args=mults, astype=np.ndarray\n )\n mult_attrs = []\n for attr in attrs: # Outputs\n\n zipped = nested_zip(attr, mults)\n\n def zip_mult(zipped_attr_mults):\n attr = zipped_attr_mults[0]\n mults = zipped_attr_mults[1]\n return attr * mults\n\n attr = nested_map(\n zipped, zip_mult, check_accessor=lambda x: x[0]\n )\n mult_attrs.append(attr)\n attrs = mult_attrs\n results.attributions = attrs # : Outputs[Inputs[TensorLike]]\n\n return results\n\n @staticmethod\n def __get_qoi(qoi_arg):\n \"\"\"\n Helper function to get a `QoI` object from more user-friendly primitive \n arguments.\n \"\"\"\n # TODO(klas): we could potentially do some basic error catching here,\n # for example, making sure the index for a given channel is in range.\n\n if isinstance(qoi_arg, QoI):\n # We were already given a QoI, so return it.\n return qoi_arg\n\n elif callable(qoi_arg):\n # If we were given a callable, treat that function as a QoI.\n return LambdaQoI(qoi_arg)\n\n elif isinstance(qoi_arg, int):\n # If we receive an int, we take it to be the class/channel index\n # (whether it's a class or channel depends on the layer the quantity\n # is for, but `InternalChannelQoI` generalizes to both).\n return InternalChannelQoI(qoi_arg)\n\n elif isinstance(qoi_arg, DATA_CONTAINER_TYPE):\n # If we receive a DATA_CONTAINER_TYPE, we take it to be two classes\n # for which we are performing a comparative quantity of interest.\n if len(qoi_arg) == 2:\n return ComparativeQoI(*qoi_arg)\n\n else:\n raise ValueError(\n 'Tuple or list argument for `qoi` must have length 2'\n )\n\n elif isinstance(qoi_arg, str):\n # We can specify `MaxClassQoI` via the string 'max'.\n if qoi_arg == 'max':\n return MaxClassQoI()\n\n else:\n raise ValueError(\n 'String argument for `qoi` must be one of the following:\\n'\n ' - \"max\"'\n )\n\n else:\n raise ValueError('Unrecognized argument type for `qoi`')\n\n @staticmethod\n def __get_doi(doi_arg, cut=None):\n \"\"\"\n Helper function to get a `DoI` object from more user-friendly primitive \n arguments.\n \"\"\"\n if isinstance(doi_arg, DoI):\n # We were already given a DoI, so return it.\n return doi_arg\n\n elif isinstance(doi_arg, str):\n # We can specify `PointDoi` via the string 'point', or `LinearDoi`\n # via the string 'linear'.\n if doi_arg == 'point':\n return PointDoi(cut=cut)\n\n elif doi_arg == 'linear':\n return LinearDoi(cut=cut)\n\n else:\n raise ValueError(\n 'String argument for `doi` must be one of the following:\\n'\n ' - \"point\"\\n'\n ' - \"linear\"'\n )\n\n else:\n raise ValueError('Unrecognized argument type for `doi`')\n\n @staticmethod\n def __get_slice(slice_arg):\n \"\"\"\n Helper function to get a `Slice` object from more user-friendly\n primitive arguments.\n \"\"\"\n if isinstance(slice_arg, Slice):\n # We are already given a Slice, so return it.\n return slice_arg\n\n elif (isinstance(slice_arg, Cut) or isinstance(slice_arg, int) or\n isinstance(slice_arg, str) or slice_arg is None or\n slice_arg == 0):\n\n # If we receive a Cut, we take it to be the Cut of the start layer.\n return Slice(InternalInfluence.__get_cut(slice_arg), OutputCut())\n\n elif isinstance(slice_arg, DATA_CONTAINER_TYPE):\n # If we receive a DATA_CONTAINER_TYPE, we take it to be the start\n # and end layer of the slice.\n if len(slice_arg) == 2:\n if slice_arg[1] is None:\n return Slice(\n InternalInfluence.__get_cut(slice_arg[0]), OutputCut()\n )\n else:\n return Slice(\n InternalInfluence.__get_cut(slice_arg[0]),\n InternalInfluence.__get_cut(slice_arg[1])\n )\n\n else:\n raise ValueError(\n 'Tuple or list argument for `cuts` must have length 2'\n )\n\n else:\n raise ValueError('Unrecognized argument type for `cuts`')\n\n @staticmethod\n def __get_cut(cut_arg):\n \"\"\"\n Helper function to get a `Cut` object from more user-friendly primitive\n arguments.\n \"\"\"\n if isinstance(cut_arg, Cut):\n # We are already given a Cut, so return it.\n return cut_arg\n\n elif cut_arg is None or cut_arg == 0:\n # If we receive None or zero, we take it to be the input cut.\n return InputCut()\n\n # TODO(klas): may want a bit more validation here.\n elif isinstance(cut_arg, int) or isinstance(cut_arg, str):\n return Cut(cut_arg)\n\n else:\n raise ValueError('Unrecognized argument type for cut')\n\n @staticmethod\n def __concatenate_doi(D: Inputs[Uniform[TensorLike]]) -> Inputs[TensorLike]:\n # Returns one TensorLike for each model input.\n if len(D[0]) == 0:\n raise ValueError(\n 'Got empty distribution of interest. `DoI` must return at '\n 'least one point.'\n )\n # TODO: should this always be done in numpy or can we do it in backend?\n D = nested_cast(backend=get_backend(), args=D, astype=np.ndarray)\n ret = nested_map(D, np.concatenate, nest=1)\n return ret\n
"},{"location":"trulens_explain/api/attribution/#trulens_explain.trulens.nn.attribution.InternalInfluence.__get_cut","title":"
__get_cut(cut_arg) staticmethod","text":"
Helper function to get a Cut object from more user-friendly primitive arguments.
Source code in
trulens_explain/trulens/nn/attribution.py @staticmethod\ndef __get_cut(cut_arg):\n \"\"\"\n Helper function to get a `Cut` object from more user-friendly primitive\n arguments.\n \"\"\"\n if isinstance(cut_arg, Cut):\n # We are already given a Cut, so return it.\n return cut_arg\n\n elif cut_arg is None or cut_arg == 0:\n # If we receive None or zero, we take it to be the input cut.\n return InputCut()\n\n # TODO(klas): may want a bit more validation here.\n elif isinstance(cut_arg, int) or isinstance(cut_arg, str):\n return Cut(cut_arg)\n\n else:\n raise ValueError('Unrecognized argument type for cut')\n
"},{"location":"trulens_explain/api/attribution/#trulens_explain.trulens.nn.attribution.InternalInfluence.__get_doi","title":"
__get_doi(doi_arg, cut=None) staticmethod","text":"
Helper function to get a DoI object from more user-friendly primitive arguments.
Source code in
trulens_explain/trulens/nn/attribution.py @staticmethod\ndef __get_doi(doi_arg, cut=None):\n \"\"\"\n Helper function to get a `DoI` object from more user-friendly primitive \n arguments.\n \"\"\"\n if isinstance(doi_arg, DoI):\n # We were already given a DoI, so return it.\n return doi_arg\n\n elif isinstance(doi_arg, str):\n # We can specify `PointDoi` via the string 'point', or `LinearDoi`\n # via the string 'linear'.\n if doi_arg == 'point':\n return PointDoi(cut=cut)\n\n elif doi_arg == 'linear':\n return LinearDoi(cut=cut)\n\n else:\n raise ValueError(\n 'String argument for `doi` must be one of the following:\\n'\n ' - \"point\"\\n'\n ' - \"linear\"'\n )\n\n else:\n raise ValueError('Unrecognized argument type for `doi`')\n
"},{"location":"trulens_explain/api/attribution/#trulens_explain.trulens.nn.attribution.InternalInfluence.__get_qoi","title":"
__get_qoi(qoi_arg) staticmethod","text":"
Helper function to get a QoI object from more user-friendly primitive arguments.
Source code in
trulens_explain/trulens/nn/attribution.py @staticmethod\ndef __get_qoi(qoi_arg):\n \"\"\"\n Helper function to get a `QoI` object from more user-friendly primitive \n arguments.\n \"\"\"\n # TODO(klas): we could potentially do some basic error catching here,\n # for example, making sure the index for a given channel is in range.\n\n if isinstance(qoi_arg, QoI):\n # We were already given a QoI, so return it.\n return qoi_arg\n\n elif callable(qoi_arg):\n # If we were given a callable, treat that function as a QoI.\n return LambdaQoI(qoi_arg)\n\n elif isinstance(qoi_arg, int):\n # If we receive an int, we take it to be the class/channel index\n # (whether it's a class or channel depends on the layer the quantity\n # is for, but `InternalChannelQoI` generalizes to both).\n return InternalChannelQoI(qoi_arg)\n\n elif isinstance(qoi_arg, DATA_CONTAINER_TYPE):\n # If we receive a DATA_CONTAINER_TYPE, we take it to be two classes\n # for which we are performing a comparative quantity of interest.\n if len(qoi_arg) == 2:\n return ComparativeQoI(*qoi_arg)\n\n else:\n raise ValueError(\n 'Tuple or list argument for `qoi` must have length 2'\n )\n\n elif isinstance(qoi_arg, str):\n # We can specify `MaxClassQoI` via the string 'max'.\n if qoi_arg == 'max':\n return MaxClassQoI()\n\n else:\n raise ValueError(\n 'String argument for `qoi` must be one of the following:\\n'\n ' - \"max\"'\n )\n\n else:\n raise ValueError('Unrecognized argument type for `qoi`')\n
"},{"location":"trulens_explain/api/attribution/#trulens_explain.trulens.nn.attribution.InternalInfluence.__get_slice","title":"
__get_slice(slice_arg) staticmethod","text":"
Helper function to get a Slice object from more user-friendly primitive arguments.
Source code in
trulens_explain/trulens/nn/attribution.py @staticmethod\ndef __get_slice(slice_arg):\n \"\"\"\n Helper function to get a `Slice` object from more user-friendly\n primitive arguments.\n \"\"\"\n if isinstance(slice_arg, Slice):\n # We are already given a Slice, so return it.\n return slice_arg\n\n elif (isinstance(slice_arg, Cut) or isinstance(slice_arg, int) or\n isinstance(slice_arg, str) or slice_arg is None or\n slice_arg == 0):\n\n # If we receive a Cut, we take it to be the Cut of the start layer.\n return Slice(InternalInfluence.__get_cut(slice_arg), OutputCut())\n\n elif isinstance(slice_arg, DATA_CONTAINER_TYPE):\n # If we receive a DATA_CONTAINER_TYPE, we take it to be the start\n # and end layer of the slice.\n if len(slice_arg) == 2:\n if slice_arg[1] is None:\n return Slice(\n InternalInfluence.__get_cut(slice_arg[0]), OutputCut()\n )\n else:\n return Slice(\n InternalInfluence.__get_cut(slice_arg[0]),\n InternalInfluence.__get_cut(slice_arg[1])\n )\n\n else:\n raise ValueError(\n 'Tuple or list argument for `cuts` must have length 2'\n )\n\n else:\n raise ValueError('Unrecognized argument type for `cuts`')\n
"},{"location":"trulens_explain/api/attribution/#trulens_explain.trulens.nn.attribution.InternalInfluence.__init__","title":"
__init__(model, cuts, qoi, doi, multiply_activation=True, return_grads=False, return_doi=False, *args, **kwargs)","text":"
Parameters:
Name Type Description Default
model ModelWrapper Model for which attributions are calculated.
required
cuts SliceLike The slice to use when computing the attributions. The slice keeps track of the layer whose output attributions are calculated and the layer for which the quantity of interest is computed. Expects a Slice object, or a related type that can be interpreted as a Slice, as documented below.
If a single Cut object is given, it is assumed to be the cut representing the layer for which attributions are calculated (i.e., from_cut in Slice) and the layer for the quantity of interest (i.e., to_cut in slices.Slice) is taken to be the output of the network. If a tuple or list of two Cuts is given, they are assumed to be from_cut and to_cut, respectively.
A cut (or the cuts within the tuple) can also be represented as an int, str, or None. If an int is given, it represents the index of a layer in model. If a str is given, it represents the name of a layer in model. None is an alternative for slices.InputCut.
required
qoi QoiLike Quantity of interest to attribute. Expects a QoI object, or a related type that can be interpreted as a QoI, as documented below.
If an int is given, the quantity of interest is taken to be the slice output for the class/neuron/channel specified by the given integer, i.e.,
quantities.InternalChannelQoI(qoi)\n
If a tuple or list of two integers is given, then the quantity of interest is taken to be the comparative quantity for the class given by the first integer against the class given by the second integer, i.e.,
quantities.ComparativeQoI(*qoi)\n
If a callable is given, it is interpreted as a function representing the QoI, i.e.,
quantities.LambdaQoI(qoi)\n
If the string, 'max', is given, the quantity of interest is taken to be the output for the class with the maximum score, i.e.,
quantities.MaxClassQoI()\n
required
doi DoiLike Distribution of interest over inputs. Expects a DoI object, or a related type that can be interpreted as a DoI, as documented below.
If the string, 'point', is given, the distribution is taken to be the single point passed to attributions, i.e.,
distributions.PointDoi()\n
If the string, 'linear', is given, the distribution is taken to be the linear interpolation from the zero input to the point passed to attributions, i.e.,
distributions.LinearDoi()\n
required
multiply_activation bool Whether to multiply the gradient result by its corresponding activation, thus converting from \"influence space\" to \"attribution space.\"
True Source code in
trulens_explain/trulens/nn/attribution.py def __init__(\n self,\n model: ModelWrapper,\n cuts: SliceLike,\n qoi: QoiLike,\n doi: DoiLike,\n multiply_activation: bool = True,\n return_grads: bool = False,\n return_doi: bool = False,\n *args,\n **kwargs\n):\n \"\"\"\n Parameters:\n model:\n Model for which attributions are calculated.\n\n cuts: \n The slice to use when computing the attributions. The slice \n keeps track of the layer whose output attributions are \n calculated and the layer for which the quantity of interest is \n computed. Expects a `Slice` object, or a related type that can\n be interpreted as a `Slice`, as documented below.\n\n If a single `Cut` object is given, it is assumed to be the cut \n representing the layer for which attributions are calculated \n (i.e., `from_cut` in `Slice`) and the layer for the quantity of \n interest (i.e., `to_cut` in `slices.Slice`) is taken to be the \n output of the network. If a tuple or list of two `Cut`s is \n given, they are assumed to be `from_cut` and `to_cut`, \n respectively.\n\n A cut (or the cuts within the tuple) can also be represented as \n an `int`, `str`, or `None`. If an `int` is given, it represents \n the index of a layer in `model`. If a `str` is given, it \n represents the name of a layer in `model`. `None` is an \n alternative for `slices.InputCut`.\n\n qoi:\n Quantity of interest to attribute. Expects a `QoI` object, or a\n related type that can be interpreted as a `QoI`, as documented\n below.\n\n If an `int` is given, the quantity of interest is taken to be \n the slice output for the class/neuron/channel specified by the \n given integer, i.e., \n ```python\n quantities.InternalChannelQoI(qoi)\n ```\n\n If a tuple or list of two integers is given, then the quantity \n of interest is taken to be the comparative quantity for the \n class given by the first integer against the class given by the \n second integer, i.e., \n ```python\n quantities.ComparativeQoI(*qoi)\n ```\n\n If a callable is given, it is interpreted as a function\n representing the QoI, i.e.,\n ```python\n quantities.LambdaQoI(qoi)\n ```\n\n If the string, `'max'`, is given, the quantity of interest is \n taken to be the output for the class with the maximum score, \n i.e., \n ```python\n quantities.MaxClassQoI()\n ```\n\n doi:\n Distribution of interest over inputs. Expects a `DoI` object, or\n a related type that can be interpreted as a `DoI`, as documented\n below.\n\n If the string, `'point'`, is given, the distribution is taken to\n be the single point passed to `attributions`, i.e., \n ```python\n distributions.PointDoi()\n ```\n\n If the string, `'linear'`, is given, the distribution is taken \n to be the linear interpolation from the zero input to the point \n passed to `attributions`, i.e., \n ```python\n distributions.LinearDoi()\n ```\n\n multiply_activation:\n Whether to multiply the gradient result by its corresponding\n activation, thus converting from \"*influence space*\" to \n \"*attribution space*.\"\n \"\"\"\n super().__init__(model, *args, **kwargs)\n\n self.slice = InternalInfluence.__get_slice(cuts)\n self.qoi = InternalInfluence.__get_qoi(qoi)\n self.doi = InternalInfluence.__get_doi(doi, cut=self.slice.from_cut)\n self._do_multiply = multiply_activation\n self._return_grads = return_grads\n self._return_doi = return_doi\n
"},{"location":"trulens_explain/api/distributions/","title":"Distributions of Interest","text":"
The distribution of interest lets us specify the set of samples over which we want our explanations to be faithful. In some cases, we may want to explain the model\u2019s behavior on a particular record, whereas other times we may be interested in a more general behavior over a distribution of samples.
"},{"location":"trulens_explain/api/distributions/#trulens_explain.trulens.nn.distributions.DoI","title":"
DoI","text":"
Bases: ABC
Interface for distributions of interest. The Distribution of Interest (DoI) specifies the samples over which an attribution method is aggregated.
Source code in
trulens_explain/trulens/nn/distributions.py class DoI(AbstractBaseClass):\n \"\"\"\n Interface for distributions of interest. The *Distribution of Interest* \n (DoI) specifies the samples over which an attribution method is \n aggregated.\n \"\"\"\n\n def __init__(self, cut: Cut = None):\n \"\"\"\"Initialize DoI\n\n Parameters:\n cut (Cut, optional): \n The Cut in which the DoI will be applied. If `None`, the DoI will be\n applied to the input. otherwise, the distribution should be applied\n to the latent space defined by the cut. \n \"\"\"\n self._cut = cut\n\n def __str__(self):\n return render_object(self, ['_cut'])\n\n def _wrap_public_call(\n self, z: Inputs[TensorLike], *, model_inputs: ModelInputs\n ) -> Inputs[Uniform[TensorLike]]:\n \"\"\"Same as __call__ but input and output types are more specific and\n less permissive. Formats the inputs for special cases that might be more\n convenient for the user's __call__ implementation and formats its return\n back to the consistent type.\"\"\"\n\n z: Inputs[TensorLike] = om_of_many(z)\n\n if accepts_model_inputs(self.__call__):\n ret = self.__call__(z, model_inputs=model_inputs)\n else:\n ret = self.__call__(z)\n # Wrap the public doi generator with appropriate type aliases.\n if isinstance(ret, DATA_CONTAINER_TYPE):\n if isinstance(ret[0], DATA_CONTAINER_TYPE):\n ret = Inputs(Uniform(x) for x in ret)\n else:\n ret = Uniform(ret)\n\n ret: Inputs[Uniform[TensorLike]] = many_of_om(\n ret, innertype=Uniform\n )\n else:\n ret: ArgsLike = [ret]\n return ret\n\n @abstractmethod\n def __call__(\n self,\n z: OM[Inputs, TensorLike],\n *,\n model_inputs: Optional[ModelInputs] = None\n ) -> OM[Inputs, Uniform[TensorLike]]:\n \"\"\"\n Computes the distribution of interest from an initial point. If z:\n TensorLike is given, we assume there is only 1 input to the DoI layer. If\n z: List[TensorLike] is given, it provides all of the inputs to the DoI\n layer. \n\n Either way, we always return List[List[TensorLike]] (alias\n Inputs[Uniform[TensorLike]]) with outer list spanning layer inputs, and\n inner list spanning a distribution's instance.\n\n Parameters:\n z:\n Input point from which the distribution is derived. If\n list/tuple, the point is defined by multiple tensors.\n model_inputs:\n Optional wrapped model input arguments that produce value z at\n cut.\n\n Returns:\n List of points which are all assigned equal probability mass in the\n distribution of interest, i.e., the distribution of interest is a\n discrete, uniform distribution over the list of returned points. If\n z is multi-input, returns a distribution for each input.\n \"\"\"\n raise NotImplementedError\n\n # @property\n def cut(self) -> Cut:\n \"\"\"\n Returns:\n The Cut in which the DoI will be applied. If `None`, the DoI will be\n applied to the input. otherwise, the distribution should be applied\n to the latent space defined by the cut. \n \"\"\"\n return self._cut\n\n def _wrap_public_get_activation_multiplier(\n self, activation: Inputs[TensorLike], *, model_inputs: ModelInputs\n ) -> Inputs[TensorLike]:\n \"\"\"Same as get_activation_multiplier but without \"one-or-more\". \"\"\"\n\n activations: OM[Inputs, TensorLike] = om_of_many(activation)\n\n # get_activation_multiplier is public\n if accepts_model_inputs(self.get_activation_multiplier):\n ret: OM[Inputs, TensorLike] = self.get_activation_multiplier(\n activations, model_inputs=model_inputs\n )\n else:\n ret: OM[Inputs,\n TensorLike] = self.get_activation_multiplier(activations)\n\n ret: Inputs[TensorLike] = many_of_om(ret)\n\n return ret\n\n def get_activation_multiplier(\n self,\n activation: OM[Inputs, TensorLike],\n *,\n model_inputs: Optional[ModelInputs] = None\n ) -> OM[Inputs, TensorLike]:\n \"\"\"\n Returns a term to multiply the gradient by to convert from \"*influence\n space*\" to \"*attribution space*\". Conceptually, \"influence space\"\n corresponds to the potential effect of a slight increase in each\n feature, while \"attribution space\" corresponds to an approximation of\n the net marginal contribution to the quantity of interest of each\n feature.\n\n Parameters:\n activation:\n The activation of the layer the DoI is applied to. DoI may be\n multi-input in which case activation will be a list.\n model_inputs:\n Optional wrapped model input arguments that produce activation\n at cut.\n\n Returns:\n An array with the same shape as ``activation`` that will be\n multiplied by the gradient to obtain the attribution. The default\n implementation of this method simply returns ``activation``. If\n activation is multi-input, returns one multiplier for each.\n \"\"\"\n return om_of_many(activation)\n\n def _assert_cut_contains_only_one_tensor(self, x):\n if isinstance(x, DATA_CONTAINER_TYPE) and len(x) == 1:\n x = x[0]\n if isinstance(x, MAP_CONTAINER_TYPE) and len(x) == 1:\n x = list(x.values())[0]\n\n if isinstance(x, list):\n raise DoiCutSupportError(\n '\\n\\n'\n 'Cut provided to distribution of interest was comprised of '\n 'multiple tensors, but `{}` is only defined for cuts comprised '\n 'of a single tensor (received a list of {} tensors).\\n'\n '\\n'\n 'Either (1) select a slice where the `to_cut` corresponds to a '\n 'single tensor, or (2) implement/use a `DoI` object that '\n 'supports lists of tensors, i.e., where the parameter, `z`, to '\n '`__call__` is expected/allowed to be a list of {} tensors.'.\n format(self.__class__.__name__, len(x), len(x))\n )\n\n elif not (isinstance(x, np.ndarray) or get_backend().is_tensor(x)):\n raise ValueError(\n '`{}` expected to receive an instance of `Tensor` or '\n '`np.ndarray`, but received an instance of {}'.format(\n self.__class__.__name__, type(x)\n )\n )\n
"},{"location":"trulens_explain/api/distributions/#trulens_explain.trulens.nn.distributions.DoI.__call__","title":"
__call__(z, *, model_inputs=None) abstractmethod","text":"
Computes the distribution of interest from an initial point. If z: TensorLike is given, we assume there is only 1 input to the DoI layer. If z: List[TensorLike] is given, it provides all of the inputs to the DoI layer.
Either way, we always return List[List[TensorLike]] (alias Inputs[Uniform[TensorLike]]) with outer list spanning layer inputs, and inner list spanning a distribution's instance.
Parameters:
Name Type Description Default
z OM[Inputs, TensorLike] Input point from which the distribution is derived. If list/tuple, the point is defined by multiple tensors.
required
model_inputs Optional[ModelInputs] Optional wrapped model input arguments that produce value z at cut.
None Returns:
Type Description
OM[Inputs, Uniform[TensorLike]] List of points which are all assigned equal probability mass in the
OM[Inputs, Uniform[TensorLike]] distribution of interest, i.e., the distribution of interest is a
OM[Inputs, Uniform[TensorLike]] discrete, uniform distribution over the list of returned points. If
OM[Inputs, Uniform[TensorLike]] z is multi-input, returns a distribution for each input.
Source code in
trulens_explain/trulens/nn/distributions.py @abstractmethod\ndef __call__(\n self,\n z: OM[Inputs, TensorLike],\n *,\n model_inputs: Optional[ModelInputs] = None\n) -> OM[Inputs, Uniform[TensorLike]]:\n \"\"\"\n Computes the distribution of interest from an initial point. If z:\n TensorLike is given, we assume there is only 1 input to the DoI layer. If\n z: List[TensorLike] is given, it provides all of the inputs to the DoI\n layer. \n\n Either way, we always return List[List[TensorLike]] (alias\n Inputs[Uniform[TensorLike]]) with outer list spanning layer inputs, and\n inner list spanning a distribution's instance.\n\n Parameters:\n z:\n Input point from which the distribution is derived. If\n list/tuple, the point is defined by multiple tensors.\n model_inputs:\n Optional wrapped model input arguments that produce value z at\n cut.\n\n Returns:\n List of points which are all assigned equal probability mass in the\n distribution of interest, i.e., the distribution of interest is a\n discrete, uniform distribution over the list of returned points. If\n z is multi-input, returns a distribution for each input.\n \"\"\"\n raise NotImplementedError\n
"},{"location":"trulens_explain/api/distributions/#trulens_explain.trulens.nn.distributions.DoI.__init__","title":"
__init__(cut=None)","text":"
\"Initialize DoI
Parameters:
Name Type Description Default
cut Cut The Cut in which the DoI will be applied. If None, the DoI will be applied to the input. otherwise, the distribution should be applied to the latent space defined by the cut.
None Source code in
trulens_explain/trulens/nn/distributions.py def __init__(self, cut: Cut = None):\n \"\"\"\"Initialize DoI\n\n Parameters:\n cut (Cut, optional): \n The Cut in which the DoI will be applied. If `None`, the DoI will be\n applied to the input. otherwise, the distribution should be applied\n to the latent space defined by the cut. \n \"\"\"\n self._cut = cut\n
"},{"location":"trulens_explain/api/distributions/#trulens_explain.trulens.nn.distributions.DoI.cut","title":"
cut()","text":"
Returns:
Type Description
Cut The Cut in which the DoI will be applied. If None, the DoI will be
Cut applied to the input. otherwise, the distribution should be applied
Cut to the latent space defined by the cut.
Source code in
trulens_explain/trulens/nn/distributions.py def cut(self) -> Cut:\n \"\"\"\n Returns:\n The Cut in which the DoI will be applied. If `None`, the DoI will be\n applied to the input. otherwise, the distribution should be applied\n to the latent space defined by the cut. \n \"\"\"\n return self._cut\n
"},{"location":"trulens_explain/api/distributions/#trulens_explain.trulens.nn.distributions.DoI.get_activation_multiplier","title":"
get_activation_multiplier(activation, *, model_inputs=None)","text":"
Returns a term to multiply the gradient by to convert from \"influence space\" to \"attribution space\". Conceptually, \"influence space\" corresponds to the potential effect of a slight increase in each feature, while \"attribution space\" corresponds to an approximation of the net marginal contribution to the quantity of interest of each feature.
Parameters:
Name Type Description Default
activation OM[Inputs, TensorLike] The activation of the layer the DoI is applied to. DoI may be multi-input in which case activation will be a list.
required
model_inputs Optional[ModelInputs] Optional wrapped model input arguments that produce activation at cut.
None Returns:
Type Description
OM[Inputs, TensorLike] An array with the same shape as activation that will be
OM[Inputs, TensorLike] multiplied by the gradient to obtain the attribution. The default
OM[Inputs, TensorLike] implementation of this method simply returns activation. If
OM[Inputs, TensorLike] activation is multi-input, returns one multiplier for each.
Source code in
trulens_explain/trulens/nn/distributions.py def get_activation_multiplier(\n self,\n activation: OM[Inputs, TensorLike],\n *,\n model_inputs: Optional[ModelInputs] = None\n) -> OM[Inputs, TensorLike]:\n \"\"\"\n Returns a term to multiply the gradient by to convert from \"*influence\n space*\" to \"*attribution space*\". Conceptually, \"influence space\"\n corresponds to the potential effect of a slight increase in each\n feature, while \"attribution space\" corresponds to an approximation of\n the net marginal contribution to the quantity of interest of each\n feature.\n\n Parameters:\n activation:\n The activation of the layer the DoI is applied to. DoI may be\n multi-input in which case activation will be a list.\n model_inputs:\n Optional wrapped model input arguments that produce activation\n at cut.\n\n Returns:\n An array with the same shape as ``activation`` that will be\n multiplied by the gradient to obtain the attribution. The default\n implementation of this method simply returns ``activation``. If\n activation is multi-input, returns one multiplier for each.\n \"\"\"\n return om_of_many(activation)\n
"},{"location":"trulens_explain/api/distributions/#trulens_explain.trulens.nn.distributions.DoiCutSupportError","title":"
DoiCutSupportError","text":"
Bases: ValueError
Exception raised if the distribution of interest is called on a cut whose output is not supported by the distribution of interest.
Source code in
trulens_explain/trulens/nn/distributions.py class DoiCutSupportError(ValueError):\n \"\"\"\n Exception raised if the distribution of interest is called on a cut whose\n output is not supported by the distribution of interest.\n \"\"\"\n pass\n
"},{"location":"trulens_explain/api/distributions/#trulens_explain.trulens.nn.distributions.GaussianDoi","title":"
GaussianDoi","text":"
Bases: DoI
Distribution representing a Gaussian ball around the point. Used by Smooth Gradients.
Source code in
trulens_explain/trulens/nn/distributions.py class GaussianDoi(DoI):\n \"\"\"\n Distribution representing a Gaussian ball around the point. Used by Smooth\n Gradients.\n \"\"\"\n\n def __init__(self, var: float, resolution: int, cut: Cut = None):\n \"\"\"\n Parameters:\n var:\n The variance of the Gaussian noise to be added around the point.\n\n resolution:\n Number of samples returned by each call to this DoI.\n cut (Cut, optional): \n The Cut in which the DoI will be applied. If `None`, the DoI will be\n applied to the input. otherwise, the distribution should be applied\n to the latent space defined by the cut. \n \"\"\"\n super(GaussianDoi, self).__init__(cut)\n self._var = var\n self._resolution = resolution\n\n def __str__(self):\n return render_object(self, ['_cut', '_var', '_resolution'])\n\n def __call__(self, z: OM[Inputs,\n TensorLike]) -> OM[Inputs, Uniform[TensorLike]]:\n # Public interface.\n\n B = get_backend()\n self._assert_cut_contains_only_one_tensor(z)\n\n def gauss_of_input(z: TensorLike) -> Uniform[TensorLike]:\n # TODO: make a pytorch backend with the same interface to use in places like these.\n\n if B.is_tensor(z):\n # Tensor implementation.\n return [\n z + B.random_normal_like(z, var=self._var)\n for _ in range(self._resolution)\n ] # Uniform\n\n else:\n # Array implementation.\n return [\n z + np.random.normal(0., np.sqrt(self._var), z.shape)\n for _ in range(self._resolution)\n ] # Uniform\n\n z: Inputs[TensorLike] = many_of_om(z)\n\n return om_of_many(nested_map(z, gauss_of_input))\n
"},{"location":"trulens_explain/api/distributions/#trulens_explain.trulens.nn.distributions.GaussianDoi.__init__","title":"
__init__(var, resolution, cut=None)","text":"
Parameters:
Name Type Description Default
var float The variance of the Gaussian noise to be added around the point.
required
resolution int Number of samples returned by each call to this DoI.
required
cut Cut The Cut in which the DoI will be applied. If None, the DoI will be applied to the input. otherwise, the distribution should be applied to the latent space defined by the cut.
None Source code in
trulens_explain/trulens/nn/distributions.py def __init__(self, var: float, resolution: int, cut: Cut = None):\n \"\"\"\n Parameters:\n var:\n The variance of the Gaussian noise to be added around the point.\n\n resolution:\n Number of samples returned by each call to this DoI.\n cut (Cut, optional): \n The Cut in which the DoI will be applied. If `None`, the DoI will be\n applied to the input. otherwise, the distribution should be applied\n to the latent space defined by the cut. \n \"\"\"\n super(GaussianDoi, self).__init__(cut)\n self._var = var\n self._resolution = resolution\n
"},{"location":"trulens_explain/api/distributions/#trulens_explain.trulens.nn.distributions.LinearDoi","title":"
LinearDoi","text":"
Bases: DoI
Distribution representing the linear interpolation between a baseline and the given point. Used by Integrated Gradients.
Source code in
trulens_explain/trulens/nn/distributions.py class LinearDoi(DoI):\n \"\"\"\n Distribution representing the linear interpolation between a baseline and \n the given point. Used by Integrated Gradients.\n \"\"\"\n\n def __init__(\n self,\n baseline: BaselineLike = None,\n resolution: int = 10,\n *,\n cut: Cut = None,\n ):\n \"\"\"\n The DoI for point, `z`, will be a uniform distribution over the points\n on the line segment connecting `z` to `baseline`, approximated by a\n sample of `resolution` points equally spaced along this segment.\n\n Parameters:\n cut (Cut, optional, from DoI): \n The Cut in which the DoI will be applied. If `None`, the DoI\n will be applied to the input. otherwise, the distribution should\n be applied to the latent space defined by the cut. \n baseline (BaselineLike, optional):\n The baseline to interpolate from. Must be same shape as the\n space the distribution acts over, i.e., the shape of the points,\n `z`, eventually passed to `__call__`. If `cut` is `None`, this\n must be the same shape as the input, otherwise this must be the\n same shape as the latent space defined by the cut. If `None` is\n given, `baseline` will be the zero vector in the appropriate\n shape. If the baseline is callable, it is expected to return the\n `baseline`, given `z` and optional model arguments.\n resolution (int):\n Number of points returned by each call to this DoI. A higher\n resolution is more computationally expensive, but gives a better\n approximation of the DoI this object mathematically represents.\n \"\"\"\n super(LinearDoi, self).__init__(cut)\n self._baseline = baseline\n self._resolution = resolution\n\n @property\n def baseline(self) -> BaselineLike:\n return self._baseline\n\n @property\n def resolution(self) -> int:\n return self._resolution\n\n def __str__(self):\n return render_object(self, ['_cut', '_baseline', '_resolution'])\n\n def __call__(\n self,\n z: OM[Inputs, TensorLike],\n *,\n model_inputs: Optional[ModelInputs] = None\n ) -> OM[Inputs, Uniform[TensorLike]]:\n\n self._assert_cut_contains_only_one_tensor(z)\n\n z: Inputs[TensorLike] = many_of_om(z)\n\n baseline = self._compute_baseline(z, model_inputs=model_inputs)\n\n r = 1. if self._resolution == 1 else self._resolution - 1.\n zipped = nested_zip(z, baseline)\n\n def zipped_interpolate(zipped_z_baseline):\n \"\"\"interpolates zipped elements\n\n Args:\n zipped_z_baseline: A tuple expecting the first element to be the z_val, and second to be the baseline.\n\n Returns:\n a list of interpolations from z to baseline\n \"\"\"\n z_ = zipped_z_baseline[0]\n b_ = zipped_z_baseline[1]\n return [ # Uniform\n (1. - i / r) * z_ + i / r * b_\n for i in range(self._resolution)\n ]\n\n ret = om_of_many(\n nested_map(\n zipped, zipped_interpolate, check_accessor=lambda x: x[0]\n )\n )\n\n return ret\n\n def get_activation_multiplier(\n self,\n activation: OM[Inputs, TensorLike],\n *,\n model_inputs: Optional[ModelInputs] = None\n ) -> Inputs[TensorLike]:\n \"\"\"\n Returns a term to multiply the gradient by to convert from \"*influence \n space*\" to \"*attribution space*\". Conceptually, \"influence space\"\n corresponds to the potential effect of a slight increase in each \n feature, while \"attribution space\" corresponds to an approximation of\n the net marginal contribution to the quantity of interest of each \n feature.\n\n Parameters:\n activation:\n The activation of the layer the DoI is applied to.\n\n Returns:\n The activation adjusted by the baseline passed to the constructor.\n \"\"\"\n\n activation: Inputs[TensorLike] = many_of_om(activation)\n\n baseline: Inputs[TensorLike] = self._compute_baseline(\n activation, model_inputs=model_inputs\n )\n\n if baseline is None:\n return activation\n\n zipped = nested_zip(activation, baseline)\n\n def zipped_subtract(zipped_activation_baseline):\n \"\"\"subtracts zipped elements\n\n Args:\n zipped_activation_baseline: A tuple expecting the first element to be the activation, and second to be the baseline.\n\n Returns:\n a subtraction of activation and baseline\n \"\"\"\n activation = zipped_activation_baseline[0]\n baseline = zipped_activation_baseline[1]\n return activation - baseline\n\n ret = nested_map(zipped, zipped_subtract, check_accessor=lambda x: x[0])\n return ret\n\n def _compute_baseline(\n self,\n z: Inputs[TensorLike],\n *,\n model_inputs: Optional[ModelInputs] = None\n ) -> Inputs[TensorLike]:\n\n B = get_backend()\n\n _baseline: BaselineLike = self.baseline # user-provided\n\n if isinstance(_baseline, Callable):\n if accepts_model_inputs(_baseline):\n _baseline: OM[Inputs, TensorLike] = many_of_om(\n _baseline(om_of_many(z), model_inputs=model_inputs)\n )\n else:\n _baseline: OM[Inputs, TensorLike] = many_of_om(\n _baseline(om_of_many(z))\n )\n\n else:\n _baseline: OM[Inputs, TensorLike]\n\n if _baseline is None:\n _baseline: Inputs[TensorLike] = nested_map(z, B.zeros_like)\n else:\n _baseline: Inputs[TensorLike] = many_of_om(_baseline)\n # Came from user; could have been single or multiple inputs.\n tensor_wrapper = TensorAKs(args=z)\n # Cast to either Tensor or numpy.ndarray to match what was given in z.\n return nested_cast(\n backend=B,\n args=_baseline,\n astype=type(tensor_wrapper.first_batchable(B))\n )\n
"},{"location":"trulens_explain/api/distributions/#trulens_explain.trulens.nn.distributions.LinearDoi.__init__","title":"
__init__(baseline=None, resolution=10, *, cut=None)","text":"
The DoI for point, z, will be a uniform distribution over the points on the line segment connecting z to baseline, approximated by a sample of resolution points equally spaced along this segment.
Parameters:
Name Type Description Default
cut Cut, optional, from DoI The Cut in which the DoI will be applied. If None, the DoI will be applied to the input. otherwise, the distribution should be applied to the latent space defined by the cut.
None baseline BaselineLike The baseline to interpolate from. Must be same shape as the space the distribution acts over, i.e., the shape of the points, z, eventually passed to __call__. If cut is None, this must be the same shape as the input, otherwise this must be the same shape as the latent space defined by the cut. If None is given, baseline will be the zero vector in the appropriate shape. If the baseline is callable, it is expected to return the baseline, given z and optional model arguments.
None resolution int Number of points returned by each call to this DoI. A higher resolution is more computationally expensive, but gives a better approximation of the DoI this object mathematically represents.
10 Source code in
trulens_explain/trulens/nn/distributions.py def __init__(\n self,\n baseline: BaselineLike = None,\n resolution: int = 10,\n *,\n cut: Cut = None,\n):\n \"\"\"\n The DoI for point, `z`, will be a uniform distribution over the points\n on the line segment connecting `z` to `baseline`, approximated by a\n sample of `resolution` points equally spaced along this segment.\n\n Parameters:\n cut (Cut, optional, from DoI): \n The Cut in which the DoI will be applied. If `None`, the DoI\n will be applied to the input. otherwise, the distribution should\n be applied to the latent space defined by the cut. \n baseline (BaselineLike, optional):\n The baseline to interpolate from. Must be same shape as the\n space the distribution acts over, i.e., the shape of the points,\n `z`, eventually passed to `__call__`. If `cut` is `None`, this\n must be the same shape as the input, otherwise this must be the\n same shape as the latent space defined by the cut. If `None` is\n given, `baseline` will be the zero vector in the appropriate\n shape. If the baseline is callable, it is expected to return the\n `baseline`, given `z` and optional model arguments.\n resolution (int):\n Number of points returned by each call to this DoI. A higher\n resolution is more computationally expensive, but gives a better\n approximation of the DoI this object mathematically represents.\n \"\"\"\n super(LinearDoi, self).__init__(cut)\n self._baseline = baseline\n self._resolution = resolution\n
"},{"location":"trulens_explain/api/distributions/#trulens_explain.trulens.nn.distributions.LinearDoi.get_activation_multiplier","title":"
get_activation_multiplier(activation, *, model_inputs=None)","text":"
Returns a term to multiply the gradient by to convert from \"influence space\" to \"attribution space\". Conceptually, \"influence space\" corresponds to the potential effect of a slight increase in each feature, while \"attribution space\" corresponds to an approximation of the net marginal contribution to the quantity of interest of each feature.
Parameters:
Name Type Description Default
activation OM[Inputs, TensorLike] The activation of the layer the DoI is applied to.
required
Returns:
Type Description
Inputs[TensorLike] The activation adjusted by the baseline passed to the constructor.
Source code in
trulens_explain/trulens/nn/distributions.py def get_activation_multiplier(\n self,\n activation: OM[Inputs, TensorLike],\n *,\n model_inputs: Optional[ModelInputs] = None\n) -> Inputs[TensorLike]:\n \"\"\"\n Returns a term to multiply the gradient by to convert from \"*influence \n space*\" to \"*attribution space*\". Conceptually, \"influence space\"\n corresponds to the potential effect of a slight increase in each \n feature, while \"attribution space\" corresponds to an approximation of\n the net marginal contribution to the quantity of interest of each \n feature.\n\n Parameters:\n activation:\n The activation of the layer the DoI is applied to.\n\n Returns:\n The activation adjusted by the baseline passed to the constructor.\n \"\"\"\n\n activation: Inputs[TensorLike] = many_of_om(activation)\n\n baseline: Inputs[TensorLike] = self._compute_baseline(\n activation, model_inputs=model_inputs\n )\n\n if baseline is None:\n return activation\n\n zipped = nested_zip(activation, baseline)\n\n def zipped_subtract(zipped_activation_baseline):\n \"\"\"subtracts zipped elements\n\n Args:\n zipped_activation_baseline: A tuple expecting the first element to be the activation, and second to be the baseline.\n\n Returns:\n a subtraction of activation and baseline\n \"\"\"\n activation = zipped_activation_baseline[0]\n baseline = zipped_activation_baseline[1]\n return activation - baseline\n\n ret = nested_map(zipped, zipped_subtract, check_accessor=lambda x: x[0])\n return ret\n
"},{"location":"trulens_explain/api/distributions/#trulens_explain.trulens.nn.distributions.PointDoi","title":"
PointDoi","text":"
Bases: DoI
Distribution that puts all probability mass on a single point.
Source code in
trulens_explain/trulens/nn/distributions.py class PointDoi(DoI):\n \"\"\"\n Distribution that puts all probability mass on a single point.\n \"\"\"\n\n def __init__(self, cut: Cut = None):\n \"\"\"\"Initialize PointDoI\n\n Parameters:\n cut (Cut, optional): \n The Cut in which the DoI will be applied. If `None`, the DoI will be\n applied to the input. otherwise, the distribution should be applied\n to the latent space defined by the cut. \n \"\"\"\n super(PointDoi, self).__init__(cut)\n\n def __call__(\n self,\n z: OM[Inputs, TensorLike],\n *,\n model_inputs: Optional[ModelInputs] = None\n ) -> OM[Inputs, Uniform[TensorLike]]:\n\n z: Inputs[TensorLike] = many_of_om(z)\n\n return om_of_many(nested_map(z, lambda x: [x]))\n
"},{"location":"trulens_explain/api/distributions/#trulens_explain.trulens.nn.distributions.PointDoi.__init__","title":"
__init__(cut=None)","text":"
\"Initialize PointDoI
Parameters:
Name Type Description Default
cut Cut The Cut in which the DoI will be applied. If None, the DoI will be applied to the input. otherwise, the distribution should be applied to the latent space defined by the cut.
None Source code in
trulens_explain/trulens/nn/distributions.py def __init__(self, cut: Cut = None):\n \"\"\"\"Initialize PointDoI\n\n Parameters:\n cut (Cut, optional): \n The Cut in which the DoI will be applied. If `None`, the DoI will be\n applied to the input. otherwise, the distribution should be applied\n to the latent space defined by the cut. \n \"\"\"\n super(PointDoi, self).__init__(cut)\n
"},{"location":"trulens_explain/api/model_wrappers/","title":"Model Wrappers","text":"
The TruLens library is designed to support models implemented via a variety of different popular python neural network frameworks: Keras (with TensorFlow or Theano backend), TensorFlow, and Pytorch. Models developed with different frameworks implement things (e.g., gradient computations) a number of different ways. We define framework specific ModelWrapper instances to create a unified model API, providing the same functionality to models that are implemented in disparate frameworks. In order to compute attributions for a model, we provide a trulens.nn.models.get_model_wrapper function that will return an appropriate ModelWrapper instance.
Some parameters are exclusively utilized for specific frameworks and are outlined in the parameter descriptions.
"},{"location":"trulens_explain/api/model_wrappers/#trulens_explain.trulens.nn.models.get_model_wrapper","title":"
get_model_wrapper(model, *, logit_layer=None, replace_softmax=False, softmax_layer=-1, custom_objects=None, device=None, input_tensors=None, output_tensors=None, internal_tensor_dict=None, default_feed_dict=None, session=None, backend=None, force_eval=True, **kwargs)","text":"
Returns a ModelWrapper implementation that exposes the components needed for computing attributions.
Parameters:
Name Type Description Default
model ModelLike The model to wrap. If using the TensorFlow 1 backend, this is expected to be a graph object.
required
logit_layer Supported for Keras and Pytorch models. Specifies the name or index of the layer that produces the logit predictions.
None replace_softmax bool Supported for Keras models only. If true, the activation function in the softmax layer (specified by softmax_layer) will be changed to a 'linear' activation.
False softmax_layer Supported for Keras models only. Specifies the layer that performs the softmax. This layer should have an activation attribute. Only used when replace_softmax is true.
-1 custom_objects Optional, for use with Keras models only. A dictionary of custom objects used by the Keras model.
None device str Optional, for use with Pytorch models only. A string specifying the device to run the model on.
None input_tensors Required for use with TensorFlow 1 graph models only. A list of tensors representing the input to the model graph.
None output_tensors Required for use with TensorFlow 1 graph models only. A list of tensors representing the output to the model graph.
None internal_tensor_dict Optional, for use with TensorFlow 1 graph models only. A dictionary mapping user-selected layer names to the internal tensors in the model graph that the user would like to expose. This is provided to give more human-readable names to the layers if desired. Internal tensors can also be accessed via the name given to them by tensorflow.
None default_feed_dict Optional, for use with TensorFlow 1 graph models only. A dictionary of default values to give to tensors in the model graph.
None session Optional, for use with TensorFlow 1 graph models only. A tf.Session object to run the model graph in. If None, a new temporary session will be generated every time the model is run.
None backend Optional, for forcing a specific backend. String values recognized are pytorch, tensorflow, keras, or tf.keras.
None force_eval _Optional, True will force a model.eval() call for PyTorch models. False will retain current model state
True Returns: ModelWrapper
Source code in
trulens_explain/trulens/nn/models/__init__.py def get_model_wrapper(\n model: ModelLike,\n *,\n logit_layer=None,\n replace_softmax: bool = False,\n softmax_layer=-1,\n custom_objects=None,\n device: str = None,\n input_tensors=None,\n output_tensors=None,\n internal_tensor_dict=None,\n default_feed_dict=None,\n session=None,\n backend=None,\n force_eval=True,\n **kwargs\n):\n \"\"\"\n Returns a ModelWrapper implementation that exposes the components needed for computing attributions.\n\n Parameters:\n model:\n The model to wrap. If using the TensorFlow 1 backend, this is \n expected to be a graph object.\n\n logit_layer:\n _Supported for Keras and Pytorch models._ \n Specifies the name or index of the layer that produces the\n logit predictions. \n\n replace_softmax:\n _Supported for Keras models only._ If true, the activation\n function in the softmax layer (specified by `softmax_layer`) \n will be changed to a `'linear'` activation. \n\n softmax_layer:\n _Supported for Keras models only._ Specifies the layer that\n performs the softmax. This layer should have an `activation`\n attribute. Only used when `replace_softmax` is true.\n\n custom_objects:\n _Optional, for use with Keras models only._ A dictionary of\n custom objects used by the Keras model.\n\n device:\n _Optional, for use with Pytorch models only._ A string\n specifying the device to run the model on.\n\n input_tensors:\n _Required for use with TensorFlow 1 graph models only._ A list\n of tensors representing the input to the model graph.\n\n output_tensors:\n _Required for use with TensorFlow 1 graph models only._ A list\n of tensors representing the output to the model graph.\n\n internal_tensor_dict:\n _Optional, for use with TensorFlow 1 graph models only._ A\n dictionary mapping user-selected layer names to the internal\n tensors in the model graph that the user would like to expose.\n This is provided to give more human-readable names to the layers\n if desired. Internal tensors can also be accessed via the name\n given to them by tensorflow.\n\n default_feed_dict:\n _Optional, for use with TensorFlow 1 graph models only._ A\n dictionary of default values to give to tensors in the model\n graph.\n\n session:\n _Optional, for use with TensorFlow 1 graph models only._ A \n `tf.Session` object to run the model graph in. If `None`, a new\n temporary session will be generated every time the model is run.\n\n backend:\n _Optional, for forcing a specific backend._ String values recognized\n are pytorch, tensorflow, keras, or tf.keras.\n\n force_eval:\n _Optional, True will force a model.eval() call for PyTorch models. False\n will retain current model state\n\n Returns: ModelWrapper\n \"\"\"\n\n if 'input_shape' in kwargs:\n tru_logger.deprecate(\n f\"get_model_wrapper: input_shape parameter is no longer used and will be removed in the future\"\n )\n del kwargs['input_shape']\n if 'input_dtype' in kwargs:\n tru_logger.deprecate(\n f\"get_model_wrapper: input_dtype parameter is no longer used and will be removed in the future\"\n )\n del kwargs['input_dtype']\n\n # get existing backend\n B = get_backend(suppress_warnings=True)\n\n if backend is None:\n backend = discern_backend(model)\n tru_logger.info(\n \"Detected {} backend for {}.\".format(\n backend.name.lower(), type(model)\n )\n )\n else:\n backend = Backend.from_name(backend)\n if B is None or (backend is not Backend.UNKNOWN and B.backend != backend):\n tru_logger.info(\n \"Changing backend from {} to {}.\".format(\n None if B is None else B.backend, backend\n )\n )\n os.environ['TRULENS_BACKEND'] = backend.name.lower()\n B = get_backend()\n else:\n tru_logger.info(\"Using backend {}.\".format(B.backend))\n tru_logger.info(\n \"If this seems incorrect, you can force the correct backend by passing the `backend` parameter directly into your get_model_wrapper call.\"\n )\n if B.backend.is_keras_derivative():\n from trulens.nn.models.keras import KerasModelWrapper\n return KerasModelWrapper(\n model,\n logit_layer=logit_layer,\n replace_softmax=replace_softmax,\n softmax_layer=softmax_layer,\n custom_objects=custom_objects\n )\n\n elif B.backend == Backend.PYTORCH:\n from trulens.nn.models.pytorch import PytorchModelWrapper\n return PytorchModelWrapper(\n model,\n logit_layer=logit_layer,\n device=device,\n force_eval=force_eval\n )\n elif B.backend == Backend.TENSORFLOW:\n import tensorflow as tf\n if tf.__version__.startswith('2'):\n from trulens.nn.models.tensorflow_v2 import Tensorflow2ModelWrapper\n return Tensorflow2ModelWrapper(\n model,\n logit_layer=logit_layer,\n replace_softmax=replace_softmax,\n softmax_layer=softmax_layer,\n custom_objects=custom_objects\n )\n else:\n from trulens.nn.models.tensorflow_v1 import TensorflowModelWrapper\n if input_tensors is None:\n tru_logger.error(\n 'tensorflow1 model must pass parameter: input_tensors'\n )\n if output_tensors is None:\n tru_logger.error(\n 'tensorflow1 model must pass parameter: output_tensors'\n )\n return TensorflowModelWrapper(\n model,\n input_tensors=input_tensors,\n output_tensors=output_tensors,\n internal_tensor_dict=internal_tensor_dict,\n session=session\n )\n
"},{"location":"trulens_explain/api/quantities/","title":"Quantities of Interest","text":"
A Quantity of Interest (QoI) is a function of the output that determines the network output behavior that the attributions describe.
The quantity of interest lets us specify what we want to explain. Often, this is the output of the network corresponding to a particular class, addressing, e.g., \"Why did the model classify a given image as a car?\" However, we could also consider various combinations of outputs, allowing us to ask more specific questions, such as, \"Why did the model classify a given image as a sedan and not a convertible?\" The former may highlight general \u201ccar features,\u201d such as tires, while the latter (called a comparative explanation) might focus on the roof of the car, a \u201ccar feature\u201d not shared by convertibles.
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.ClassQoI","title":"
ClassQoI","text":"
Bases: QoI
Quantity of interest for attributing output towards a specified class.
Source code in
trulens_explain/trulens/nn/quantities.py class ClassQoI(QoI):\n \"\"\"\n Quantity of interest for attributing output towards a specified class.\n \"\"\"\n\n def __init__(self, cl: int):\n \"\"\"\n Parameters:\n cl:\n The index of the class the QoI is for.\n \"\"\"\n self.cl = cl\n\n def __str__(self):\n return render_object(self, [\"cl\"])\n\n def __call__(self, y: TensorLike) -> TensorLike:\n self._assert_cut_contains_only_one_tensor(y)\n\n return y[:, self.cl]\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.ClassQoI.__init__","title":"
__init__(cl)","text":"
Parameters:
Name Type Description Default
cl int The index of the class the QoI is for.
required Source code in
trulens_explain/trulens/nn/quantities.py def __init__(self, cl: int):\n \"\"\"\n Parameters:\n cl:\n The index of the class the QoI is for.\n \"\"\"\n self.cl = cl\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.ClassSeqQoI","title":"
ClassSeqQoI","text":"
Bases: QoI
Quantity of interest for attributing output towards a sequence of classes for each input.
Source code in
trulens_explain/trulens/nn/quantities.py class ClassSeqQoI(QoI):\n \"\"\"\n Quantity of interest for attributing output towards a sequence of classes \n for each input.\n \"\"\"\n\n def __init__(self, seq_labels: List[int]):\n \"\"\"\n Parameters:\n seq_labels:\n A sequence of classes corresponding to each input.\n \"\"\"\n self.seq_labels = seq_labels\n\n def __call__(self, y):\n\n self._assert_cut_contains_only_one_tensor(y)\n assert get_backend().shape(y)[0] == len(self.seq_labels)\n\n return y[:, self.seq_labels]\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.ClassSeqQoI.__init__","title":"
__init__(seq_labels)","text":"
Parameters:
Name Type Description Default
seq_labels List[int] A sequence of classes corresponding to each input.
required Source code in
trulens_explain/trulens/nn/quantities.py def __init__(self, seq_labels: List[int]):\n \"\"\"\n Parameters:\n seq_labels:\n A sequence of classes corresponding to each input.\n \"\"\"\n self.seq_labels = seq_labels\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.ComparativeQoI","title":"
ComparativeQoI","text":"
Bases: QoI
Quantity of interest for attributing network output towards a given class, relative to another.
Source code in
trulens_explain/trulens/nn/quantities.py class ComparativeQoI(QoI):\n \"\"\"\n Quantity of interest for attributing network output towards a given class, \n relative to another.\n \"\"\"\n\n def __init__(self, cl1: int, cl2: int):\n \"\"\"\n Parameters:\n cl1:\n The index of the class the QoI is for.\n cl2:\n The index of the class to compare against.\n \"\"\"\n self.cl1 = cl1\n self.cl2 = cl2\n\n def __str__(self):\n return render_object(self, [\"cl1\", \"cl2\"])\n\n def __call__(self, y: TensorLike) -> TensorLike:\n\n self._assert_cut_contains_only_one_tensor(y)\n\n return y[:, self.cl1] - y[:, self.cl2]\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.ComparativeQoI.__init__","title":"
__init__(cl1, cl2)","text":"
Parameters:
Name Type Description Default
cl1 int The index of the class the QoI is for.
required
cl2 int The index of the class to compare against.
required Source code in
trulens_explain/trulens/nn/quantities.py def __init__(self, cl1: int, cl2: int):\n \"\"\"\n Parameters:\n cl1:\n The index of the class the QoI is for.\n cl2:\n The index of the class to compare against.\n \"\"\"\n self.cl1 = cl1\n self.cl2 = cl2\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.InternalChannelQoI","title":"
InternalChannelQoI","text":"
Bases: QoI
Quantity of interest for attributing output towards the output of an internal convolutional layer channel, aggregating using a specified operation.
Also works for non-convolutional dense layers, where the given neuron's activation is returned.
Source code in
trulens_explain/trulens/nn/quantities.py class InternalChannelQoI(QoI):\n \"\"\"\n Quantity of interest for attributing output towards the output of an \n internal convolutional layer channel, aggregating using a specified \n operation.\n\n Also works for non-convolutional dense layers, where the given neuron's\n activation is returned.\n \"\"\"\n\n @staticmethod\n def _batch_sum(x):\n \"\"\"\n Sums batched 2D channels, leaving the batch dimension unchanged.\n \"\"\"\n return get_backend().sum(x, axis=(1, 2))\n\n def __init__(\n self,\n channel: Union[int, List[int]],\n channel_axis: Optional[int] = None,\n agg_fn: Optional[Callable] = None\n ):\n \"\"\"\n Parameters:\n channel:\n Channel to return. If a list is provided, then the quantity sums \n over each of the channels in the list.\n\n channel_axis:\n Channel dimension index, if relevant, e.g., for 2D convolutional\n layers. If `channel_axis` is `None`, then the channel axis of \n the relevant backend will be used. This argument is not used \n when the channels are scalars, e.g., for dense layers.\n\n agg_fn:\n Function with which to aggregate the remaining dimensions \n (except the batch dimension) in order to get a single scalar \n value for each channel. If `agg_fn` is `None` then a sum over \n each neuron in the channel will be taken. This argument is not \n used when the channels are scalars, e.g., for dense layers.\n \"\"\"\n if channel_axis is None:\n channel_axis = get_backend().channel_axis\n if agg_fn is None:\n agg_fn = InternalChannelQoI._batch_sum\n\n self._channel_ax = channel_axis\n self._agg_fn = agg_fn\n self._channels = channel if isinstance(channel, list) else [channel]\n\n def __call__(self, y: TensorLike) -> TensorLike:\n B = get_backend()\n self._assert_cut_contains_only_one_tensor(y)\n\n if len(B.int_shape(y)) == 2:\n return sum([y[:, ch] for ch in self._channels])\n\n elif len(B.int_shape(y)) == 3:\n return sum([self._agg_fn(y[:, :, ch]) for ch in self._channel])\n\n elif len(B.int_shape(y)) == 4:\n if self._channel_ax == 1:\n return sum([self._agg_fn(y[:, ch]) for ch in self._channels])\n\n elif self._channel_ax == 3:\n return sum(\n [self._agg_fn(y[:, :, :, ch]) for ch in self._channels]\n )\n\n else:\n raise ValueError(\n 'Unsupported channel axis for convolutional layer: {}'.\n format(self._channel_ax)\n )\n\n else:\n raise QoiCutSupportError(\n 'Unsupported tensor rank for `InternalChannelQoI`: {}'.format(\n len(B.int_shape(y))\n )\n )\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.InternalChannelQoI.__init__","title":"
__init__(channel, channel_axis=None, agg_fn=None)","text":"
Parameters:
Name Type Description Default
channel Union[int, List[int]] Channel to return. If a list is provided, then the quantity sums over each of the channels in the list.
required
channel_axis Optional[int] Channel dimension index, if relevant, e.g., for 2D convolutional layers. If channel_axis is None, then the channel axis of the relevant backend will be used. This argument is not used when the channels are scalars, e.g., for dense layers.
None agg_fn Optional[Callable] Function with which to aggregate the remaining dimensions (except the batch dimension) in order to get a single scalar value for each channel. If agg_fn is None then a sum over each neuron in the channel will be taken. This argument is not used when the channels are scalars, e.g., for dense layers.
None Source code in
trulens_explain/trulens/nn/quantities.py def __init__(\n self,\n channel: Union[int, List[int]],\n channel_axis: Optional[int] = None,\n agg_fn: Optional[Callable] = None\n):\n \"\"\"\n Parameters:\n channel:\n Channel to return. If a list is provided, then the quantity sums \n over each of the channels in the list.\n\n channel_axis:\n Channel dimension index, if relevant, e.g., for 2D convolutional\n layers. If `channel_axis` is `None`, then the channel axis of \n the relevant backend will be used. This argument is not used \n when the channels are scalars, e.g., for dense layers.\n\n agg_fn:\n Function with which to aggregate the remaining dimensions \n (except the batch dimension) in order to get a single scalar \n value for each channel. If `agg_fn` is `None` then a sum over \n each neuron in the channel will be taken. This argument is not \n used when the channels are scalars, e.g., for dense layers.\n \"\"\"\n if channel_axis is None:\n channel_axis = get_backend().channel_axis\n if agg_fn is None:\n agg_fn = InternalChannelQoI._batch_sum\n\n self._channel_ax = channel_axis\n self._agg_fn = agg_fn\n self._channels = channel if isinstance(channel, list) else [channel]\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.LambdaQoI","title":"
LambdaQoI","text":"
Bases: QoI
Generic quantity of interest allowing the user to specify a function of the model's output as the QoI.
Source code in
trulens_explain/trulens/nn/quantities.py class LambdaQoI(QoI):\n \"\"\"\n Generic quantity of interest allowing the user to specify a function of the\n model's output as the QoI.\n \"\"\"\n\n def __init__(self, function: Callable):\n \"\"\"\n Parameters:\n function:\n A callable that takes a single argument representing the model's \n tensor output and returns a differentiable batched scalar tensor \n representing the QoI.\n \"\"\"\n if len(signature(function).parameters) != 1:\n raise ValueError(\n 'QoI function must take exactly 1 argument, but provided '\n 'function takes {} arguments'.format(\n len(signature(function).parameters)\n )\n )\n\n self.function = function\n\n def __call__(self, y: TensorLike) -> TensorLike:\n return self.function(y)\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.LambdaQoI.__init__","title":"
__init__(function)","text":"
Parameters:
Name Type Description Default
function Callable A callable that takes a single argument representing the model's tensor output and returns a differentiable batched scalar tensor representing the QoI.
required Source code in
trulens_explain/trulens/nn/quantities.py def __init__(self, function: Callable):\n \"\"\"\n Parameters:\n function:\n A callable that takes a single argument representing the model's \n tensor output and returns a differentiable batched scalar tensor \n representing the QoI.\n \"\"\"\n if len(signature(function).parameters) != 1:\n raise ValueError(\n 'QoI function must take exactly 1 argument, but provided '\n 'function takes {} arguments'.format(\n len(signature(function).parameters)\n )\n )\n\n self.function = function\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.MaxClassQoI","title":"
MaxClassQoI","text":"
Bases: QoI
Quantity of interest for attributing output towards the maximum-predicted class.
Source code in
trulens_explain/trulens/nn/quantities.py class MaxClassQoI(QoI):\n \"\"\"\n Quantity of interest for attributing output towards the maximum-predicted \n class.\n \"\"\"\n\n def __init__(\n self, axis: int = 1, activation: Union[Callable, str, None] = None\n ):\n \"\"\"\n Parameters:\n axis:\n Output dimension over which max operation is taken.\n\n activation:\n Activation function to be applied to the output before taking \n the max. If `activation` is a string, use the corresponding \n named activation function implemented by the backend. The \n following strings are currently supported as shorthands for the\n respective standard activation functions:\n\n - `'sigmoid'` \n - `'softmax'` \n\n If `activation` is `None`, no activation function is applied to\n the input.\n \"\"\"\n self._axis = axis\n self.activation = activation\n\n def __str__(self):\n return render_object(self, [\"_axis\", \"activation\"])\n\n def __call__(self, y: TensorLike) -> TensorLike:\n self._assert_cut_contains_only_one_tensor(y)\n\n if self.activation is not None:\n if isinstance(self.activation, str):\n self.activation = self.activation.lower()\n if self.activation in ['sigmoid', 'softmax']:\n y = getattr(get_backend(), self.activation)(y)\n\n else:\n raise NotImplementedError(\n 'This activation function is not currently supported '\n 'by the backend'\n )\n else:\n y = self.activation(y)\n\n return get_backend().max(y, axis=self._axis)\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.MaxClassQoI.__init__","title":"
__init__(axis=1, activation=None)","text":"
Parameters:
Name Type Description Default
axis int Output dimension over which max operation is taken.
1 activation Union[Callable, str, None] Activation function to be applied to the output before taking the max. If activation is a string, use the corresponding named activation function implemented by the backend. The following strings are currently supported as shorthands for the respective standard activation functions:
If activation is None, no activation function is applied to the input.
None Source code in
trulens_explain/trulens/nn/quantities.py def __init__(\n self, axis: int = 1, activation: Union[Callable, str, None] = None\n):\n \"\"\"\n Parameters:\n axis:\n Output dimension over which max operation is taken.\n\n activation:\n Activation function to be applied to the output before taking \n the max. If `activation` is a string, use the corresponding \n named activation function implemented by the backend. The \n following strings are currently supported as shorthands for the\n respective standard activation functions:\n\n - `'sigmoid'` \n - `'softmax'` \n\n If `activation` is `None`, no activation function is applied to\n the input.\n \"\"\"\n self._axis = axis\n self.activation = activation\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.QoI","title":"
QoI","text":"
Bases: ABC
Interface for quantities of interest. The Quantity of Interest (QoI) is a function of the output specified by the slice that determines the network output behavior that the attributions describe.
Source code in
trulens_explain/trulens/nn/quantities.py class QoI(AbstractBaseClass):\n \"\"\"\n Interface for quantities of interest. The *Quantity of Interest* (QoI) is a\n function of the output specified by the slice that determines the network \n output behavior that the attributions describe.\n \"\"\"\n\n def __str__(self):\n return render_object(self, [])\n\n # TODO: Need to give a seperate value of y at target instance here since\n # these are values are interventions. Cannot presently define a QoI that says:\n # logits of the predicted class for each instance.\n # Issue GH-72 . Task MLNN-415 .\n\n def _wrap_public_call(self, y: Outputs[Tensor]) -> Outputs[Tensor]:\n \"\"\"\n Wrap a public call that may result in one or more tensors. Signature of\n this class is not specific while public calls are flexible.\n \"\"\"\n\n return many_of_om(self.__call__(om_of_many(y)))\n\n @abstractmethod\n def __call__(self, y: OM[Outputs, Tensor]) -> OM[Outputs, Tensor]:\n \"\"\"\n Computes the distribution of interest from an initial point.\n\n Parameters:\n y:\n Output point from which the quantity is derived. Must be a\n differentiable tensor.\n\n Returns:\n A differentiable batched scalar tensor representing the QoI.\n \"\"\"\n raise NotImplementedError\n\n def _assert_cut_contains_only_one_tensor(self, x):\n if isinstance(x, DATA_CONTAINER_TYPE):\n raise QoiCutSupportError(\n 'Cut provided to quantity of interest was comprised of '\n 'multiple tensors, but `{}` is only defined for cuts comprised '\n 'of a single tensor (received a list of {} tensors).\\n'\n '\\n'\n 'Either (1) select a slice where the `to_cut` corresponds to a '\n 'single tensor, or (2) implement/use a `QoI` object that '\n 'supports lists of tensors, i.e., where the parameter, `x`, to '\n '`__call__` is expected/allowed to be a list of {} tensors.'.\n format(self.__class__.__name__, len(x), len(x))\n )\n\n elif not get_backend().is_tensor(x):\n raise ValueError(\n '`{}` expected to receive an instance of `Tensor`, but '\n 'received an instance of {}'.format(\n self.__class__.__name__, type(x)\n )\n )\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.QoI.__call__","title":"
__call__(y) abstractmethod","text":"
Computes the distribution of interest from an initial point.
Parameters:
Name Type Description Default
y OM[Outputs, Tensor] Output point from which the quantity is derived. Must be a differentiable tensor.
required
Returns:
Type Description
OM[Outputs, Tensor] A differentiable batched scalar tensor representing the QoI.
Source code in
trulens_explain/trulens/nn/quantities.py @abstractmethod\ndef __call__(self, y: OM[Outputs, Tensor]) -> OM[Outputs, Tensor]:\n \"\"\"\n Computes the distribution of interest from an initial point.\n\n Parameters:\n y:\n Output point from which the quantity is derived. Must be a\n differentiable tensor.\n\n Returns:\n A differentiable batched scalar tensor representing the QoI.\n \"\"\"\n raise NotImplementedError\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.QoiCutSupportError","title":"
QoiCutSupportError","text":"
Bases: ValueError
Exception raised if the quantity of interest is called on a cut whose output is not supported by the quantity of interest.
Source code in
trulens_explain/trulens/nn/quantities.py class QoiCutSupportError(ValueError):\n \"\"\"\n Exception raised if the quantity of interest is called on a cut whose output\n is not supported by the quantity of interest.\n \"\"\"\n pass\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.ThresholdQoI","title":"
ThresholdQoI","text":"
Bases: QoI
Quantity of interest for attributing network output toward the difference between two regions seperated by a given threshold. I.e., the quantity of interest is the \"high\" elements minus the \"low\" elements, where the high elements have activations above the threshold and the low elements have activations below the threshold.
Use case: bianry segmentation.
Source code in
trulens_explain/trulens/nn/quantities.py class ThresholdQoI(QoI):\n \"\"\"\n Quantity of interest for attributing network output toward the difference \n between two regions seperated by a given threshold. I.e., the quantity of\n interest is the \"high\" elements minus the \"low\" elements, where the high\n elements have activations above the threshold and the low elements have \n activations below the threshold.\n\n Use case: bianry segmentation.\n \"\"\"\n\n def __init__(\n self,\n threshold: float,\n low_minus_high: bool = False,\n activation: Union[Callable, str, None] = None\n ):\n \"\"\"\n Parameters:\n threshold:\n A threshold to determine the element-wise sign of the input \n tensor. The elements with activations higher than the threshold \n will retain their sign, while the elements with activations \n lower than the threshold will have their sign flipped (or vice \n versa if `low_minus_high` is set to `True`).\n low_minus_high:\n If `True`, substract the output with activations above the \n threshold from the output with activations below the threshold. \n If `False`, substract the output with activations below the \n threshold from the output with activations above the threshold.\n activation: str or function, optional\n Activation function to be applied to the quantity before taking\n the threshold. If `activation` is a string, use the \n corresponding activation function implemented by the backend \n (currently supported: `'sigmoid'` and `'softmax'`). Otherwise, \n if `activation` is not `None`, it will be treated as a callable.\n If `activation` is `None`, do not apply an activation function \n to the quantity.\n \"\"\"\n # TODO(klas):should this support an aggregation function? By default\n # this is a sum, but it could, for example, subtract the greatest\n # positive element from the least negative element.\n self.threshold = threshold\n self.low_minus_high = low_minus_high\n self.activation = activation\n\n def __call__(self, x: TensorLike) -> TensorLike:\n B = get_backend()\n self._assert_cut_contains_only_one_tensor(x)\n\n if self.activation is not None:\n if isinstance(self.activation, str):\n self.activation = self.activation.lower()\n if self.activation in ['sigmoid', 'softmax']:\n x = getattr(B, self.activation)(x)\n else:\n raise NotImplementedError(\n 'This activation function is not currently supported '\n 'by the backend'\n )\n else:\n x = self.activation(x)\n\n # TODO(klas): is the `clone` necessary here? Not sure why it was\n # included.\n mask = B.sign(B.clone(x) - self.threshold)\n if self.low_minus_high:\n mask = -mask\n\n non_batch_dimensions = tuple(range(len(B.int_shape(x)))[1:])\n\n return B.sum(mask * x, axis=non_batch_dimensions)\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.ThresholdQoI.__init__","title":"
__init__(threshold, low_minus_high=False, activation=None)","text":"
Parameters:
Name Type Description Default
threshold float A threshold to determine the element-wise sign of the input tensor. The elements with activations higher than the threshold will retain their sign, while the elements with activations lower than the threshold will have their sign flipped (or vice versa if low_minus_high is set to True).
required
low_minus_high bool If True, substract the output with activations above the threshold from the output with activations below the threshold. If False, substract the output with activations below the threshold from the output with activations above the threshold.
False activation Union[Callable, str, None] str or function, optional Activation function to be applied to the quantity before taking the threshold. If activation is a string, use the corresponding activation function implemented by the backend (currently supported: 'sigmoid' and 'softmax'). Otherwise, if activation is not None, it will be treated as a callable. If activation is None, do not apply an activation function to the quantity.
None Source code in
trulens_explain/trulens/nn/quantities.py def __init__(\n self,\n threshold: float,\n low_minus_high: bool = False,\n activation: Union[Callable, str, None] = None\n):\n \"\"\"\n Parameters:\n threshold:\n A threshold to determine the element-wise sign of the input \n tensor. The elements with activations higher than the threshold \n will retain their sign, while the elements with activations \n lower than the threshold will have their sign flipped (or vice \n versa if `low_minus_high` is set to `True`).\n low_minus_high:\n If `True`, substract the output with activations above the \n threshold from the output with activations below the threshold. \n If `False`, substract the output with activations below the \n threshold from the output with activations above the threshold.\n activation: str or function, optional\n Activation function to be applied to the quantity before taking\n the threshold. If `activation` is a string, use the \n corresponding activation function implemented by the backend \n (currently supported: `'sigmoid'` and `'softmax'`). Otherwise, \n if `activation` is not `None`, it will be treated as a callable.\n If `activation` is `None`, do not apply an activation function \n to the quantity.\n \"\"\"\n # TODO(klas):should this support an aggregation function? By default\n # this is a sum, but it could, for example, subtract the greatest\n # positive element from the least negative element.\n self.threshold = threshold\n self.low_minus_high = low_minus_high\n self.activation = activation\n
"},{"location":"trulens_explain/api/slices/","title":"Slices","text":"
The slice, or layer, of the network provides flexibility over the level of abstraction for the explanation. In a low layer, an explanation may highlight the edges that were most important in identifying an object like a face, while in a higher layer, the explanation might highlight high-level features such as a nose or mouth. By raising the level of abstraction, explanations that generalize over larger sets of samples are possible.
Formally, A network, \\(f\\), can be broken into a slice, \\(f = g \\circ h\\), where \\(h\\) can be thought of as a pre-processor that computes features, and \\(g\\) can be thought of as a sub-model that uses the features computed by \\(h\\).
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.Cut","title":"
Cut","text":"
Bases: object
A cut is the primary building block for a slice. It determines an internal component of a network to expose. A slice if formed by two cuts.
Source code in
trulens_explain/trulens/nn/slices.py class Cut(object):\n \"\"\"\n A cut is the primary building block for a slice. It determines an internal\n component of a network to expose. A slice if formed by two cuts.\n \"\"\"\n\n def __init__(\n self,\n name: LayerIdentifier,\n anchor: str = 'out',\n accessor: Optional[Callable] = None\n ):\n \"\"\"\n Parameters:\n name:\n The name or index of a layer in the model, or a list containing\n the names/indices of mutliple layers.\n\n anchor: \n Determines whether input (`'in'`) or the output (`'out'`) tensor\n of the spcified layer should be used.\n\n accessor:\n An accessor function that operates on the layer, mapping the \n tensor (or list thereof) corresponding to the layer's \n input/output to another tensor (or list thereof). This can be \n used to, e.g., extract a particular output from a layer that \n produces a sequence of outputs. If `accessor` is `None`, the \n following accessor function will be used: \n ```python\n lambda t: t[-1] if isinstance(t, list) else t\n ```\n \"\"\"\n assert name is None or isinstance(\n name, (list, int, str)\n ), \"Cut.name must be one of: layer index, layer name, or list of names/indices of multiple layers\"\n if isinstance(name, list):\n for n in name:\n assert isinstance(\n n, (int, str)\n ), f\"Elements in Cut.name must be layer names (str) or indices (int). Got type {type(n)}\"\n anchor = str(anchor)\n assert anchor in [\n 'in', 'out'\n ], \"Cut.anchor must be one of ('in', 'out')\"\n assert accessor is None or isinstance(\n accessor, Callable\n ), \"Cut.accessor must be callable or None\"\n\n if get_backend().backend == 'pytorch':\n if (isinstance(name, int) or\n (isinstance(name, list) and isinstance(name[0], int))):\n\n tru_logger.warning(\n '\\n\\nPytorch does not have native support for indexed '\n 'layers. Using layer indices is not recommended.\\n'\n )\n\n self.name = name\n self.accessor = accessor\n self.anchor = anchor\n\n def __str__(self):\n return render_object(self, ['name', 'accessor', 'anchor'])\n\n # TODO: layer arg might need to be more specific\n def access_layer(self, layer: TensorLike) -> TensorLike:\n \"\"\"\n Applies `self.accessor` to the result of collecting the relevant \n tensor(s) associated with a layer's output.\n\n Parameters:\n layer:\n The tensor output (or input, if so specified by the anchor) of \n the layer(s) specified by this cut.\n\n Returns:\n The result of applying `self.accessor` to the given layer.\n \"\"\"\n if layer is None:\n return layer\n elif self.accessor is None:\n return layer\n else:\n layer = (\n layer[0]\n if isinstance(layer, list) and len(layer) == 1 else layer\n )\n return self.accessor(layer)\n
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.Cut.__init__","title":"
__init__(name, anchor='out', accessor=None)","text":"
Parameters:
Name Type Description Default
name LayerIdentifier The name or index of a layer in the model, or a list containing the names/indices of mutliple layers.
required
anchor str Determines whether input ('in') or the output ('out') tensor of the spcified layer should be used.
'out' accessor Optional[Callable] An accessor function that operates on the layer, mapping the tensor (or list thereof) corresponding to the layer's input/output to another tensor (or list thereof). This can be used to, e.g., extract a particular output from a layer that produces a sequence of outputs. If accessor is None, the following accessor function will be used:
lambda t: t[-1] if isinstance(t, list) else t\n
None Source code in
trulens_explain/trulens/nn/slices.py def __init__(\n self,\n name: LayerIdentifier,\n anchor: str = 'out',\n accessor: Optional[Callable] = None\n):\n \"\"\"\n Parameters:\n name:\n The name or index of a layer in the model, or a list containing\n the names/indices of mutliple layers.\n\n anchor: \n Determines whether input (`'in'`) or the output (`'out'`) tensor\n of the spcified layer should be used.\n\n accessor:\n An accessor function that operates on the layer, mapping the \n tensor (or list thereof) corresponding to the layer's \n input/output to another tensor (or list thereof). This can be \n used to, e.g., extract a particular output from a layer that \n produces a sequence of outputs. If `accessor` is `None`, the \n following accessor function will be used: \n ```python\n lambda t: t[-1] if isinstance(t, list) else t\n ```\n \"\"\"\n assert name is None or isinstance(\n name, (list, int, str)\n ), \"Cut.name must be one of: layer index, layer name, or list of names/indices of multiple layers\"\n if isinstance(name, list):\n for n in name:\n assert isinstance(\n n, (int, str)\n ), f\"Elements in Cut.name must be layer names (str) or indices (int). Got type {type(n)}\"\n anchor = str(anchor)\n assert anchor in [\n 'in', 'out'\n ], \"Cut.anchor must be one of ('in', 'out')\"\n assert accessor is None or isinstance(\n accessor, Callable\n ), \"Cut.accessor must be callable or None\"\n\n if get_backend().backend == 'pytorch':\n if (isinstance(name, int) or\n (isinstance(name, list) and isinstance(name[0], int))):\n\n tru_logger.warning(\n '\\n\\nPytorch does not have native support for indexed '\n 'layers. Using layer indices is not recommended.\\n'\n )\n\n self.name = name\n self.accessor = accessor\n self.anchor = anchor\n
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.Cut.access_layer","title":"
access_layer(layer)","text":"
Applies self.accessor to the result of collecting the relevant tensor(s) associated with a layer's output.
Parameters:
Name Type Description Default
layer TensorLike The tensor output (or input, if so specified by the anchor) of the layer(s) specified by this cut.
required
Returns:
Type Description
TensorLike The result of applying self.accessor to the given layer.
Source code in
trulens_explain/trulens/nn/slices.py def access_layer(self, layer: TensorLike) -> TensorLike:\n \"\"\"\n Applies `self.accessor` to the result of collecting the relevant \n tensor(s) associated with a layer's output.\n\n Parameters:\n layer:\n The tensor output (or input, if so specified by the anchor) of \n the layer(s) specified by this cut.\n\n Returns:\n The result of applying `self.accessor` to the given layer.\n \"\"\"\n if layer is None:\n return layer\n elif self.accessor is None:\n return layer\n else:\n layer = (\n layer[0]\n if isinstance(layer, list) and len(layer) == 1 else layer\n )\n return self.accessor(layer)\n
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.InputCut","title":"
InputCut","text":"
Bases: Cut
Special cut that selects the input(s) of a model.
Source code in
trulens_explain/trulens/nn/slices.py class InputCut(Cut):\n \"\"\"\n Special cut that selects the input(s) of a model.\n \"\"\"\n\n def __init__(self, anchor: str = 'in', accessor: Optional[Callable] = None):\n \"\"\"\n Parameters:\n anchor: \n Determines whether input (`'in'`) or the output (`'out'`) tensor\n of the spcified layer should be used.\n\n accessor:\n An accessor function that operates on the layer, mapping the \n tensor (or list thereof) corresponding to the layer's \n input/output to another tensor (or list thereof). This can be \n used to, e.g., extract a particular output from a layer that \n produces a sequence of outputs. If `accessor` is `None`, the \n following accessor function will be used: \n ```python\n lambda t: t[-1] if isinstance(t, list) else t\n ```\n \"\"\"\n super().__init__(None, anchor, accessor)\n
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.InputCut.__init__","title":"
__init__(anchor='in', accessor=None)","text":"
Parameters:
Name Type Description Default
anchor str Determines whether input ('in') or the output ('out') tensor of the spcified layer should be used.
'in' accessor Optional[Callable] An accessor function that operates on the layer, mapping the tensor (or list thereof) corresponding to the layer's input/output to another tensor (or list thereof). This can be used to, e.g., extract a particular output from a layer that produces a sequence of outputs. If accessor is None, the following accessor function will be used:
lambda t: t[-1] if isinstance(t, list) else t\n
None Source code in
trulens_explain/trulens/nn/slices.py def __init__(self, anchor: str = 'in', accessor: Optional[Callable] = None):\n \"\"\"\n Parameters:\n anchor: \n Determines whether input (`'in'`) or the output (`'out'`) tensor\n of the spcified layer should be used.\n\n accessor:\n An accessor function that operates on the layer, mapping the \n tensor (or list thereof) corresponding to the layer's \n input/output to another tensor (or list thereof). This can be \n used to, e.g., extract a particular output from a layer that \n produces a sequence of outputs. If `accessor` is `None`, the \n following accessor function will be used: \n ```python\n lambda t: t[-1] if isinstance(t, list) else t\n ```\n \"\"\"\n super().__init__(None, anchor, accessor)\n
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.LogitCut","title":"
LogitCut","text":"
Bases: Cut
Special cut that selects the logit layer of a model. The logit layer must be named 'logits' or otherwise specified by the user to the model wrapper.
Source code in
trulens_explain/trulens/nn/slices.py class LogitCut(Cut):\n \"\"\"\n Special cut that selects the logit layer of a model. The logit layer must be\n named `'logits'` or otherwise specified by the user to the model wrapper.\n \"\"\"\n\n def __init__(\n self, anchor: str = 'out', accessor: Optional[Callable] = None\n ):\n \"\"\"\n Parameters:\n anchor: \n Determines whether input (`'in'`) or the output (`'out'`) tensor\n of the spcified layer should be used.\n\n accessor:\n An accessor function that operates on the layer, mapping the \n tensor (or list thereof) corresponding to the layer's \n input/output to another tensor (or list thereof). This can be \n used to, e.g., extract a particular output from a layer that \n produces a sequence of outputs. If `accessor` is `None`, the \n following accessor function will be used: \n ```python\n lambda t: t[-1] if isinstance(t, list) else t\n ```\n \"\"\"\n super(LogitCut, self).__init__(None, anchor, accessor)\n
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.LogitCut.__init__","title":"
__init__(anchor='out', accessor=None)","text":"
Parameters:
Name Type Description Default
anchor str Determines whether input ('in') or the output ('out') tensor of the spcified layer should be used.
'out' accessor Optional[Callable] An accessor function that operates on the layer, mapping the tensor (or list thereof) corresponding to the layer's input/output to another tensor (or list thereof). This can be used to, e.g., extract a particular output from a layer that produces a sequence of outputs. If accessor is None, the following accessor function will be used:
lambda t: t[-1] if isinstance(t, list) else t\n
None Source code in
trulens_explain/trulens/nn/slices.py def __init__(\n self, anchor: str = 'out', accessor: Optional[Callable] = None\n):\n \"\"\"\n Parameters:\n anchor: \n Determines whether input (`'in'`) or the output (`'out'`) tensor\n of the spcified layer should be used.\n\n accessor:\n An accessor function that operates on the layer, mapping the \n tensor (or list thereof) corresponding to the layer's \n input/output to another tensor (or list thereof). This can be \n used to, e.g., extract a particular output from a layer that \n produces a sequence of outputs. If `accessor` is `None`, the \n following accessor function will be used: \n ```python\n lambda t: t[-1] if isinstance(t, list) else t\n ```\n \"\"\"\n super(LogitCut, self).__init__(None, anchor, accessor)\n
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.OutputCut","title":"
OutputCut","text":"
Bases: Cut
Special cut that selects the output(s) of a model.
Source code in
trulens_explain/trulens/nn/slices.py class OutputCut(Cut):\n \"\"\"\n Special cut that selects the output(s) of a model.\n \"\"\"\n\n def __init__(\n self, anchor: str = 'out', accessor: Optional[Callable] = None\n ):\n \"\"\"\n Parameters:\n anchor: \n Determines whether input (`'in'`) or the output (`'out'`) tensor\n of the spcified layer should be used.\n\n accessor:\n An accessor function that operates on the layer, mapping the \n tensor (or list thereof) corresponding to the layer's \n input/output to another tensor (or list thereof). This can be \n used to, e.g., extract a particular output from a layer that \n produces a sequence of outputs. If `accessor` is `None`, the \n following accessor function will be used: \n ```python\n lambda t: t[-1] if isinstance(t, list) else t\n ```\n \"\"\"\n super(OutputCut, self).__init__(None, anchor, accessor)\n
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.OutputCut.__init__","title":"
__init__(anchor='out', accessor=None)","text":"
Parameters:
Name Type Description Default
anchor str Determines whether input ('in') or the output ('out') tensor of the spcified layer should be used.
'out' accessor Optional[Callable] An accessor function that operates on the layer, mapping the tensor (or list thereof) corresponding to the layer's input/output to another tensor (or list thereof). This can be used to, e.g., extract a particular output from a layer that produces a sequence of outputs. If accessor is None, the following accessor function will be used:
lambda t: t[-1] if isinstance(t, list) else t\n
None Source code in
trulens_explain/trulens/nn/slices.py def __init__(\n self, anchor: str = 'out', accessor: Optional[Callable] = None\n):\n \"\"\"\n Parameters:\n anchor: \n Determines whether input (`'in'`) or the output (`'out'`) tensor\n of the spcified layer should be used.\n\n accessor:\n An accessor function that operates on the layer, mapping the \n tensor (or list thereof) corresponding to the layer's \n input/output to another tensor (or list thereof). This can be \n used to, e.g., extract a particular output from a layer that \n produces a sequence of outputs. If `accessor` is `None`, the \n following accessor function will be used: \n ```python\n lambda t: t[-1] if isinstance(t, list) else t\n ```\n \"\"\"\n super(OutputCut, self).__init__(None, anchor, accessor)\n
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.Slice","title":"
Slice","text":"
Bases: object
Class representing a slice of a network. A network, \\(f\\), can be broken into a slice, \\(f = g \\circ h\\), where \\(h\\) can be thought of as a pre-processor that computes features, and \\(g\\) can be thought of as a sub-model that uses the features computed by \\(h\\).
A Slice object represents a slice as two Cuts, from_cut and to_cut, which are the layers corresponding to the output of \\(h\\) and \\(g\\), respectively.
Source code in
trulens_explain/trulens/nn/slices.py class Slice(object):\n \"\"\"\n Class representing a slice of a network. A network, $f$, can be broken\n into a slice, $f = g \\\\circ h$, where $h$ can be thought of as a \n pre-processor that computes features, and $g$ can be thought of as a \n sub-model that uses the features computed by $h$.\n\n A `Slice` object represents a slice as two `Cut`s, `from_cut` and `to_cut`,\n which are the layers corresponding to the output of $h$ and $g$, \n respectively.\n \"\"\"\n\n def __init__(self, from_cut: Cut, to_cut: Cut):\n \"\"\"\n Parameters:\n from_cut:\n Cut representing the output of the preprocessing function, $h$,\n in slice, $f = g \\\\circ h$.\n\n to_cut:\n Cut representing the output of the sub-model, $g$, in slice, \n $f = g \\\\circ h$.\n \"\"\"\n self._from_cut = from_cut\n self._to_cut = to_cut\n\n @property\n def from_cut(self) -> Cut:\n \"\"\"\n Cut representing the output of the preprocessing function, $h$, in \n slice, $f = g \\\\circ h$.\n \"\"\"\n return self._from_cut\n\n @property\n def to_cut(self) -> Cut:\n \"\"\"\n Cut representing the output of the sub-model, $g$, in slice, \n $f = g \\\\circ h$.\n \"\"\"\n return self._to_cut\n\n @staticmethod\n def full_network():\n \"\"\"\n Returns\n -------\n Slice\n A slice representing the entire model, i.e., :math:`f = g \\\\circ h`,\n where :math:`h` is the identity function and :math:`g = f`.\n \"\"\"\n return Slice(InputCut(), OutputCut())\n
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.Slice.from_cut","title":"
from_cut: Cut property","text":"
Cut representing the output of the preprocessing function, \\(h\\), in slice, \\(f = g \\circ h\\).
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.Slice.to_cut","title":"
to_cut: Cut property","text":"
Cut representing the output of the sub-model, \\(g\\), in slice, \\(f = g \\circ h\\).
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.Slice.__init__","title":"
__init__(from_cut, to_cut)","text":"
Parameters:
Name Type Description Default
from_cut Cut Cut representing the output of the preprocessing function, \\(h\\), in slice, \\(f = g \\circ h\\).
required
to_cut Cut Cut representing the output of the sub-model, \\(g\\), in slice, \\(f = g \\circ h\\).
required Source code in
trulens_explain/trulens/nn/slices.py def __init__(self, from_cut: Cut, to_cut: Cut):\n \"\"\"\n Parameters:\n from_cut:\n Cut representing the output of the preprocessing function, $h$,\n in slice, $f = g \\\\circ h$.\n\n to_cut:\n Cut representing the output of the sub-model, $g$, in slice, \n $f = g \\\\circ h$.\n \"\"\"\n self._from_cut = from_cut\n self._to_cut = to_cut\n
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.Slice.full_network","title":"
full_network() staticmethod","text":""},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.Slice.full_network--returns","title":"Returns","text":"
Slice A slice representing the entire model, i.e., :math:f = g \\circ h, where :math:h is the identity function and :math:g = f.
Source code in
trulens_explain/trulens/nn/slices.py @staticmethod\ndef full_network():\n \"\"\"\n Returns\n -------\n Slice\n A slice representing the entire model, i.e., :math:`f = g \\\\circ h`,\n where :math:`h` is the identity function and :math:`g = f`.\n \"\"\"\n return Slice(InputCut(), OutputCut())\n
"},{"location":"trulens_explain/api/visualizations/","title":"Visualization Methods","text":"
One clear use case for measuring attributions is for human consumption. In order to be fully leveraged by humans, explanations need to be interpretable \u2014 a large vector of numbers doesn\u2019t in general make us more confident we understand what a network is doing. We therefore view an explanation as comprised of both an attribution measurement and an interpretation of what the attribution values represent.
One obvious way to interpret attributions, particularly in the image domain, is via visualization. This module provides several visualization methods for interpreting attributions as images.
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.ChannelMaskVisualizer","title":"
ChannelMaskVisualizer","text":"
Bases: object
Uses internal influence to visualize the pixels that are most salient towards a particular internal channel or neuron.
Source code in
trulens_explain/trulens/visualizations.py class ChannelMaskVisualizer(object):\n \"\"\"\n Uses internal influence to visualize the pixels that are most salient\n towards a particular internal channel or neuron.\n \"\"\"\n\n def __init__(\n self,\n model,\n layer,\n channel,\n channel_axis=None,\n agg_fn=None,\n doi=None,\n blur=None,\n threshold=0.5,\n masked_opacity=0.2,\n combine_channels: bool = True,\n use_attr_as_opacity=None,\n positive_only=None\n ):\n \"\"\"\n Configures the default parameters for the `__call__` method (these can \n be overridden by passing in values to `__call__`).\n\n Parameters:\n model:\n The wrapped model whose channel we're visualizing.\n\n layer:\n The identifier (either index or name) of the layer in which the \n channel we're visualizing resides.\n\n channel:\n Index of the channel (for convolutional layers) or internal \n neuron (for fully-connected layers) that we'd like to visualize.\n\n channel_axis:\n If different from the channel axis specified by the backend, the\n supplied `channel_axis` will be used if operating on a \n convolutional layer with 4-D image format.\n\n agg_fn:\n Function with which to aggregate the remaining dimensions \n (except the batch dimension) in order to get a single scalar \n value for each channel; If `None`, a sum over each neuron in the\n channel will be taken. This argument is not used when the \n channels are scalars, e.g., for dense layers.\n\n doi:\n The distribution of interest to use when computing the input\n attributions towards the specified channel. If `None`, \n `PointDoI` will be used.\n\n blur:\n Gives the radius of a Gaussian blur to be applied to the \n attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels.\n\n threshold:\n Value in the range [0, 1]. Attribution values at or below the \n percentile given by `threshold` (after normalization, blurring,\n etc.) will be masked.\n\n masked_opacity: \n Value in the range [0, 1] specifying the opacity for the parts\n of the image that are masked.\n\n combine_channels:\n If `True`, the attributions will be averaged across the channel\n dimension, resulting in a 1-channel attribution map.\n\n use_attr_as_opacity:\n If `True`, instead of using `threshold` and `masked_opacity`,\n the opacity of each pixel is given by the 0-1-normalized \n attribution value.\n\n positive_only:\n If `True`, only pixels with positive attribution will be \n unmasked (or given nonzero opacity when `use_attr_as_opacity` is\n true).\n \"\"\"\n B = get_backend()\n if (B is not None and (channel_axis is None or channel_axis < 0)):\n channel_axis = B.channel_axis\n elif (channel_axis is None or channel_axis < 0):\n channel_axis = 1\n\n self.mask_visualizer = MaskVisualizer(\n blur, threshold, masked_opacity, combine_channels,\n use_attr_as_opacity, positive_only\n )\n\n self.infl_input = InternalInfluence(\n model, (InputCut(), Cut(layer)),\n InternalChannelQoI(channel, channel_axis, agg_fn),\n PointDoi() if doi is None else doi\n )\n\n def __call__(\n self,\n x,\n x_preprocessed=None,\n output_file=None,\n blur=None,\n threshold=None,\n masked_opacity=None,\n combine_channels=None\n ):\n \"\"\"\n Visualizes the given attributions by overlaying an attribution heatmap \n over the given image.\n\n Parameters\n ----------\n attributions : numpy.ndarray\n The attributions to visualize. Expected to be in 4-D image format.\n\n x : numpy.ndarray\n The original image(s) over which the attributions are calculated.\n Must be the same shape as expected by the model used with this\n visualizer.\n\n x_preprocessed : numpy.ndarray, optional\n If the model requires a preprocessed input (e.g., with the mean\n subtracted) that is different from how the image should be \n visualized, ``x_preprocessed`` should be specified. In this case \n ``x`` will be used for visualization, and ``x_preprocessed`` will be\n passed to the model when calculating attributions. Must be the same \n shape as ``x``.\n\n output_file : str, optional\n If specified, the resulting visualization will be saved to a file\n with the name given by ``output_file``.\n\n blur : float, optional\n If specified, gives the radius of a Gaussian blur to be applied to\n the attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels. If None, \n defaults to the value supplied to the constructor. Default None.\n\n threshold : float\n Value in the range [0, 1]. Attribution values at or below the \n percentile given by ``threshold`` will be masked. If None, defaults \n to the value supplied to the constructor. Default None.\n\n masked_opacity: float\n Value in the range [0, 1] specifying the opacity for the parts of\n the image that are masked. Default 0.2. If None, defaults to the \n value supplied to the constructor. Default None.\n\n combine_channels : bool\n If True, the attributions will be averaged across the channel\n dimension, resulting in a 1-channel attribution map. If None, \n defaults to the value supplied to the constructor. Default None.\n \"\"\"\n\n attrs_input = self.infl_input.attributions(\n x if x_preprocessed is None else x_preprocessed\n )\n\n return self.mask_visualizer(\n attrs_input, x, output_file, blur, threshold, masked_opacity,\n combine_channels\n )\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.ChannelMaskVisualizer.__call__","title":"
__call__(x, x_preprocessed=None, output_file=None, blur=None, threshold=None, masked_opacity=None, combine_channels=None)","text":"
Visualizes the given attributions by overlaying an attribution heatmap over the given image.
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.ChannelMaskVisualizer.__call__--parameters","title":"Parameters","text":"
attributions : numpy.ndarray The attributions to visualize. Expected to be in 4-D image format.
numpy.ndarray
The original image(s) over which the attributions are calculated. Must be the same shape as expected by the model used with this visualizer.
numpy.ndarray, optional
If the model requires a preprocessed input (e.g., with the mean subtracted) that is different from how the image should be visualized, x_preprocessed should be specified. In this case x will be used for visualization, and x_preprocessed will be passed to the model when calculating attributions. Must be the same shape as x.
str, optional
If specified, the resulting visualization will be saved to a file with the name given by output_file.
float, optional
If specified, gives the radius of a Gaussian blur to be applied to the attributions before visualizing. This can be used to help focus on salient regions rather than specific salient pixels. If None, defaults to the value supplied to the constructor. Default None.
float
Value in the range [0, 1]. Attribution values at or below the percentile given by threshold will be masked. If None, defaults to the value supplied to the constructor. Default None.
float
Value in the range [0, 1] specifying the opacity for the parts of the image that are masked. Default 0.2. If None, defaults to the value supplied to the constructor. Default None.
bool
If True, the attributions will be averaged across the channel dimension, resulting in a 1-channel attribution map. If None, defaults to the value supplied to the constructor. Default None.
Source code in
trulens_explain/trulens/visualizations.py def __call__(\n self,\n x,\n x_preprocessed=None,\n output_file=None,\n blur=None,\n threshold=None,\n masked_opacity=None,\n combine_channels=None\n):\n \"\"\"\n Visualizes the given attributions by overlaying an attribution heatmap \n over the given image.\n\n Parameters\n ----------\n attributions : numpy.ndarray\n The attributions to visualize. Expected to be in 4-D image format.\n\n x : numpy.ndarray\n The original image(s) over which the attributions are calculated.\n Must be the same shape as expected by the model used with this\n visualizer.\n\n x_preprocessed : numpy.ndarray, optional\n If the model requires a preprocessed input (e.g., with the mean\n subtracted) that is different from how the image should be \n visualized, ``x_preprocessed`` should be specified. In this case \n ``x`` will be used for visualization, and ``x_preprocessed`` will be\n passed to the model when calculating attributions. Must be the same \n shape as ``x``.\n\n output_file : str, optional\n If specified, the resulting visualization will be saved to a file\n with the name given by ``output_file``.\n\n blur : float, optional\n If specified, gives the radius of a Gaussian blur to be applied to\n the attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels. If None, \n defaults to the value supplied to the constructor. Default None.\n\n threshold : float\n Value in the range [0, 1]. Attribution values at or below the \n percentile given by ``threshold`` will be masked. If None, defaults \n to the value supplied to the constructor. Default None.\n\n masked_opacity: float\n Value in the range [0, 1] specifying the opacity for the parts of\n the image that are masked. Default 0.2. If None, defaults to the \n value supplied to the constructor. Default None.\n\n combine_channels : bool\n If True, the attributions will be averaged across the channel\n dimension, resulting in a 1-channel attribution map. If None, \n defaults to the value supplied to the constructor. Default None.\n \"\"\"\n\n attrs_input = self.infl_input.attributions(\n x if x_preprocessed is None else x_preprocessed\n )\n\n return self.mask_visualizer(\n attrs_input, x, output_file, blur, threshold, masked_opacity,\n combine_channels\n )\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.ChannelMaskVisualizer.__init__","title":"
__init__(model, layer, channel, channel_axis=None, agg_fn=None, doi=None, blur=None, threshold=0.5, masked_opacity=0.2, combine_channels=True, use_attr_as_opacity=None, positive_only=None)","text":"
Configures the default parameters for the __call__ method (these can be overridden by passing in values to __call__).
Parameters:
Name Type Description Default
model The wrapped model whose channel we're visualizing.
required
layer The identifier (either index or name) of the layer in which the channel we're visualizing resides.
required
channel Index of the channel (for convolutional layers) or internal neuron (for fully-connected layers) that we'd like to visualize.
required
channel_axis If different from the channel axis specified by the backend, the supplied channel_axis will be used if operating on a convolutional layer with 4-D image format.
None agg_fn Function with which to aggregate the remaining dimensions (except the batch dimension) in order to get a single scalar value for each channel; If None, a sum over each neuron in the channel will be taken. This argument is not used when the channels are scalars, e.g., for dense layers.
None doi The distribution of interest to use when computing the input attributions towards the specified channel. If None, PointDoI will be used.
None blur Gives the radius of a Gaussian blur to be applied to the attributions before visualizing. This can be used to help focus on salient regions rather than specific salient pixels.
None threshold Value in the range [0, 1]. Attribution values at or below the percentile given by threshold (after normalization, blurring, etc.) will be masked.
0.5 masked_opacity Value in the range [0, 1] specifying the opacity for the parts of the image that are masked.
0.2 combine_channels bool If True, the attributions will be averaged across the channel dimension, resulting in a 1-channel attribution map.
True use_attr_as_opacity If True, instead of using threshold and masked_opacity, the opacity of each pixel is given by the 0-1-normalized attribution value.
None positive_only If True, only pixels with positive attribution will be unmasked (or given nonzero opacity when use_attr_as_opacity is true).
None Source code in
trulens_explain/trulens/visualizations.py def __init__(\n self,\n model,\n layer,\n channel,\n channel_axis=None,\n agg_fn=None,\n doi=None,\n blur=None,\n threshold=0.5,\n masked_opacity=0.2,\n combine_channels: bool = True,\n use_attr_as_opacity=None,\n positive_only=None\n):\n \"\"\"\n Configures the default parameters for the `__call__` method (these can \n be overridden by passing in values to `__call__`).\n\n Parameters:\n model:\n The wrapped model whose channel we're visualizing.\n\n layer:\n The identifier (either index or name) of the layer in which the \n channel we're visualizing resides.\n\n channel:\n Index of the channel (for convolutional layers) or internal \n neuron (for fully-connected layers) that we'd like to visualize.\n\n channel_axis:\n If different from the channel axis specified by the backend, the\n supplied `channel_axis` will be used if operating on a \n convolutional layer with 4-D image format.\n\n agg_fn:\n Function with which to aggregate the remaining dimensions \n (except the batch dimension) in order to get a single scalar \n value for each channel; If `None`, a sum over each neuron in the\n channel will be taken. This argument is not used when the \n channels are scalars, e.g., for dense layers.\n\n doi:\n The distribution of interest to use when computing the input\n attributions towards the specified channel. If `None`, \n `PointDoI` will be used.\n\n blur:\n Gives the radius of a Gaussian blur to be applied to the \n attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels.\n\n threshold:\n Value in the range [0, 1]. Attribution values at or below the \n percentile given by `threshold` (after normalization, blurring,\n etc.) will be masked.\n\n masked_opacity: \n Value in the range [0, 1] specifying the opacity for the parts\n of the image that are masked.\n\n combine_channels:\n If `True`, the attributions will be averaged across the channel\n dimension, resulting in a 1-channel attribution map.\n\n use_attr_as_opacity:\n If `True`, instead of using `threshold` and `masked_opacity`,\n the opacity of each pixel is given by the 0-1-normalized \n attribution value.\n\n positive_only:\n If `True`, only pixels with positive attribution will be \n unmasked (or given nonzero opacity when `use_attr_as_opacity` is\n true).\n \"\"\"\n B = get_backend()\n if (B is not None and (channel_axis is None or channel_axis < 0)):\n channel_axis = B.channel_axis\n elif (channel_axis is None or channel_axis < 0):\n channel_axis = 1\n\n self.mask_visualizer = MaskVisualizer(\n blur, threshold, masked_opacity, combine_channels,\n use_attr_as_opacity, positive_only\n )\n\n self.infl_input = InternalInfluence(\n model, (InputCut(), Cut(layer)),\n InternalChannelQoI(channel, channel_axis, agg_fn),\n PointDoi() if doi is None else doi\n )\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.HTML","title":"
HTML","text":"
Bases: Output
HTML visualization output format.
Source code in
trulens_explain/trulens/visualizations.py class HTML(Output):\n \"\"\"HTML visualization output format.\"\"\"\n\n def __init__(self):\n try:\n self.m_html = importlib.import_module(\"html\")\n except:\n raise ImportError(\n \"HTML output requires html python module. Try 'pip install html'.\"\n )\n\n def blank(self):\n return \"\"\n\n def space(self):\n return \" \"\n\n def escape(self, s):\n return self.m_html.escape(s)\n\n def linebreak(self):\n return \"<br/>\"\n\n def line(self, s):\n return f\"<span style='padding: 2px; margin: 2px; background: gray; border-radius: 4px;'>{s}</span>\"\n\n def magnitude_colored(self, s, mag):\n red = 0.0\n green = 0.0\n if mag > 0:\n green = 1.0 # 0.5 + mag * 0.5\n red = 1.0 - mag * 0.5\n else:\n red = 1.0\n green = 1.0 + mag * 0.5\n #red = 0.5 - mag * 0.5\n\n blue = min(red, green)\n # blue = 1.0 - max(red, green)\n\n return f\"<span title='{mag:0.3f}' style='margin: 1px; padding: 1px; border-radius: 4px; background: black; color: rgb({red*255}, {green*255}, {blue*255});'>{s}</span>\"\n\n def append(self, *pieces):\n return ''.join(pieces)\n\n def render(self, s):\n return s\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.HeatmapVisualizer","title":"
HeatmapVisualizer","text":"
Bases: Visualizer
Visualizes attributions by overlaying an attribution heatmap over the original image, similar to how GradCAM visualizes attributions.
Source code in
trulens_explain/trulens/visualizations.py class HeatmapVisualizer(Visualizer):\n \"\"\"\n Visualizes attributions by overlaying an attribution heatmap over the\n original image, similar to how GradCAM visualizes attributions.\n \"\"\"\n\n def __init__(\n self,\n overlay_opacity=0.5,\n normalization_type=None,\n blur=10.,\n cmap='jet'\n ):\n \"\"\"\n Configures the default parameters for the `__call__` method (these can \n be overridden by passing in values to `__call__`).\n\n Parameters:\n overlay_opacity: float\n Value in the range [0, 1] specifying the opacity for the heatmap\n overlay.\n\n normalization_type:\n Specifies one of the following configurations for normalizing\n the attributions (each item is normalized separately):\n\n - `'unsigned_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the attributions by the maximum absolute \n attribution value.\n - `'unsigned_max_positive_centered'`: same as above, but scales\n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5. \n - `'magnitude_max'`: takes the absolute value of the \n attributions, then normalizes the attributions to the range \n [0, 1] by dividing by the maximum absolute attribution value.\n - `'magnitude_sum'`: takes the absolute value of the \n attributions, then scales them such that they sum to 1. If \n this option is used, each channel is normalized separately, \n such that each channel sums to 1.\n - `'signed_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the positive values by the maximum \n positive attribution value and the negative values by the \n minimum negative attribution value.\n - `'signed_max_positive_centered'`: same as above, but scales \n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5.\n - `'signed_sum'`: scales the positive attributions such that \n they sum to 1 and the negative attributions such that they\n scale to -1. If this option is used, each channel is \n normalized separately.\n - `'01'`: normalizes the attributions to the range [0, 1] by \n subtracting the minimum attribution value then dividing by the\n maximum attribution value.\n - `'unnormalized'`: leaves the attributions unaffected.\n\n If `None`, either `'unsigned_max'` (for single-channel data) or \n `'unsigned_max_positive_centered'` (for multi-channel data) is\n used.\n\n blur:\n Gives the radius of a Gaussian blur to be applied to the \n attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels.\n\n cmap: matplotlib.colors.Colormap | str, optional\n Colormap or name of a Colormap to use for the visualization. If \n `None`, the colormap will be chosen based on the normalization \n type. This argument is only used for single-channel data\n (including when `combine_channels` is True).\n \"\"\"\n\n super().__init__(\n combine_channels=True,\n normalization_type=normalization_type,\n blur=blur,\n cmap=cmap\n )\n\n self.default_overlay_opacity = overlay_opacity\n\n def __call__(\n self,\n attributions,\n x,\n output_file=None,\n imshow=True,\n fig=None,\n return_tiled=False,\n overlay_opacity=None,\n normalization_type=None,\n blur=None,\n cmap=None\n ) -> np.ndarray:\n \"\"\"\n Visualizes the given attributions by overlaying an attribution heatmap \n over the given image.\n\n Parameters:\n attributions:\n A `np.ndarray` containing the attributions to be visualized.\n\n x:\n A `np.ndarray` of items in the same shape as `attributions`\n corresponding to the records explained by the given \n attributions. The visualization will be superimposed onto the\n corresponding set of records.\n\n output_file:\n File name to save the visualization image to. If `None`, no\n image will be saved, but the figure can still be displayed.\n\n imshow:\n If true, a the visualization will be displayed. Otherwise the\n figure will not be displayed, but the figure can still be saved.\n\n fig:\n The `pyplot` figure to display the visualization in. If `None`,\n a new figure will be created.\n\n return_tiled:\n If true, the returned array will be in the same shape as the\n visualization, with no batch dimension and the samples in the\n batch tiled along the width and height dimensions. If false, the\n returned array will be reshaped to match `attributions`.\n\n overlay_opacity: float\n Value in the range [0, 1] specifying the opacity for the heatmap\n overlay. If `None`, defaults to the value supplied to the \n constructor.\n\n normalization_type:\n Specifies one of the following configurations for normalizing\n the attributions (each item is normalized separately):\n\n - `'unsigned_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the attributions by the maximum absolute \n attribution value.\n - `'unsigned_max_positive_centered'`: same as above, but scales\n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5. \n - `'magnitude_max'`: takes the absolute value of the \n attributions, then normalizes the attributions to the range \n [0, 1] by dividing by the maximum absolute attribution value.\n - `'magnitude_sum'`: takes the absolute value of the \n attributions, then scales them such that they sum to 1. If \n this option is used, each channel is normalized separately, \n such that each channel sums to 1.\n - `'signed_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the positive values by the maximum \n positive attribution value and the negative values by the \n minimum negative attribution value.\n - `'signed_max_positive_centered'`: same as above, but scales \n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5.\n - `'signed_sum'`: scales the positive attributions such that \n they sum to 1 and the negative attributions such that they\n scale to -1. If this option is used, each channel is \n normalized separately.\n - `'01'`: normalizes the attributions to the range [0, 1] by \n subtracting the minimum attribution value then dividing by the\n maximum attribution value.\n - `'unnormalized'`: leaves the attributions unaffected.\n\n If `None`, defaults to the value supplied to the constructor.\n\n blur:\n Gives the radius of a Gaussian blur to be applied to the \n attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels. If\n `None`, defaults to the value supplied to the constructor.\n\n cmap: matplotlib.colors.Colormap | str, optional\n Colormap or name of a Colormap to use for the visualization. If\n `None`, defaults to the value supplied to the constructor.\n\n Returns:\n A `np.ndarray` array of the numerical representation of the\n attributions as modified for the visualization. This includes \n normalization, blurring, etc.\n \"\"\"\n _, normalization_type, blur, cmap = self._check_args(\n attributions, None, normalization_type, blur, cmap\n )\n\n # Combine the channels.\n attributions = attributions.mean(\n axis=get_backend().channel_axis, keepdims=True\n )\n\n # Blur the attributions so the explanation is smoother.\n if blur:\n attributions = self._blur(attributions, blur)\n\n # Normalize the attributions.\n attributions = self._normalize(attributions, normalization_type)\n\n tiled_attributions = self.tiler.tile(attributions)\n\n # Normalize the pixels to be in the range [0, 1].\n x = self._normalize(x, '01')\n tiled_x = self.tiler.tile(x)\n\n if cmap is None:\n cmap = self.default_cmap\n\n if overlay_opacity is None:\n overlay_opacity = self.default_overlay_opacity\n\n # Display the figure:\n _fig = plt.figure() if fig is None else fig\n\n plt.axis('off')\n plt.imshow(tiled_x)\n plt.imshow(tiled_attributions, alpha=overlay_opacity, cmap=cmap)\n\n if output_file:\n plt.savefig(output_file, bbox_inches=0)\n\n if imshow:\n plt.show()\n\n elif fig is None:\n plt.close(_fig)\n\n return tiled_attributions if return_tiled else attributions\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.HeatmapVisualizer.__call__","title":"
__call__(attributions, x, output_file=None, imshow=True, fig=None, return_tiled=False, overlay_opacity=None, normalization_type=None, blur=None, cmap=None)","text":"
Visualizes the given attributions by overlaying an attribution heatmap over the given image.
Parameters:
Name Type Description Default
attributions A np.ndarray containing the attributions to be visualized.
required
x A np.ndarray of items in the same shape as attributions corresponding to the records explained by the given attributions. The visualization will be superimposed onto the corresponding set of records.
required
output_file File name to save the visualization image to. If None, no image will be saved, but the figure can still be displayed.
None imshow If true, a the visualization will be displayed. Otherwise the figure will not be displayed, but the figure can still be saved.
True fig The pyplot figure to display the visualization in. If None, a new figure will be created.
None return_tiled If true, the returned array will be in the same shape as the visualization, with no batch dimension and the samples in the batch tiled along the width and height dimensions. If false, the returned array will be reshaped to match attributions.
False overlay_opacity float Value in the range [0, 1] specifying the opacity for the heatmap overlay. If None, defaults to the value supplied to the constructor.
None normalization_type Specifies one of the following configurations for normalizing the attributions (each item is normalized separately):
'unsigned_max': normalizes the attributions to the range [-1, 1] by dividing the attributions by the maximum absolute attribution value.'unsigned_max_positive_centered': same as above, but scales the values to the range [0, 1], with negative scores less than 0.5 and positive scores greater than 0.5. 'magnitude_max': takes the absolute value of the attributions, then normalizes the attributions to the range [0, 1] by dividing by the maximum absolute attribution value.'magnitude_sum': takes the absolute value of the attributions, then scales them such that they sum to 1. If this option is used, each channel is normalized separately, such that each channel sums to 1.'signed_max': normalizes the attributions to the range [-1, 1] by dividing the positive values by the maximum positive attribution value and the negative values by the minimum negative attribution value.'signed_max_positive_centered': same as above, but scales the values to the range [0, 1], with negative scores less than 0.5 and positive scores greater than 0.5.'signed_sum': scales the positive attributions such that they sum to 1 and the negative attributions such that they scale to -1. If this option is used, each channel is normalized separately.'01': normalizes the attributions to the range [0, 1] by subtracting the minimum attribution value then dividing by the maximum attribution value.'unnormalized': leaves the attributions unaffected.
If None, defaults to the value supplied to the constructor.
None blur Gives the radius of a Gaussian blur to be applied to the attributions before visualizing. This can be used to help focus on salient regions rather than specific salient pixels. If None, defaults to the value supplied to the constructor.
None cmap matplotlib.colors.Colormap | str, optional Colormap or name of a Colormap to use for the visualization. If None, defaults to the value supplied to the constructor.
None Returns:
Type Description
ndarray A np.ndarray array of the numerical representation of the
ndarray attributions as modified for the visualization. This includes
ndarray normalization, blurring, etc.
Source code in
trulens_explain/trulens/visualizations.py def __call__(\n self,\n attributions,\n x,\n output_file=None,\n imshow=True,\n fig=None,\n return_tiled=False,\n overlay_opacity=None,\n normalization_type=None,\n blur=None,\n cmap=None\n) -> np.ndarray:\n \"\"\"\n Visualizes the given attributions by overlaying an attribution heatmap \n over the given image.\n\n Parameters:\n attributions:\n A `np.ndarray` containing the attributions to be visualized.\n\n x:\n A `np.ndarray` of items in the same shape as `attributions`\n corresponding to the records explained by the given \n attributions. The visualization will be superimposed onto the\n corresponding set of records.\n\n output_file:\n File name to save the visualization image to. If `None`, no\n image will be saved, but the figure can still be displayed.\n\n imshow:\n If true, a the visualization will be displayed. Otherwise the\n figure will not be displayed, but the figure can still be saved.\n\n fig:\n The `pyplot` figure to display the visualization in. If `None`,\n a new figure will be created.\n\n return_tiled:\n If true, the returned array will be in the same shape as the\n visualization, with no batch dimension and the samples in the\n batch tiled along the width and height dimensions. If false, the\n returned array will be reshaped to match `attributions`.\n\n overlay_opacity: float\n Value in the range [0, 1] specifying the opacity for the heatmap\n overlay. If `None`, defaults to the value supplied to the \n constructor.\n\n normalization_type:\n Specifies one of the following configurations for normalizing\n the attributions (each item is normalized separately):\n\n - `'unsigned_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the attributions by the maximum absolute \n attribution value.\n - `'unsigned_max_positive_centered'`: same as above, but scales\n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5. \n - `'magnitude_max'`: takes the absolute value of the \n attributions, then normalizes the attributions to the range \n [0, 1] by dividing by the maximum absolute attribution value.\n - `'magnitude_sum'`: takes the absolute value of the \n attributions, then scales them such that they sum to 1. If \n this option is used, each channel is normalized separately, \n such that each channel sums to 1.\n - `'signed_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the positive values by the maximum \n positive attribution value and the negative values by the \n minimum negative attribution value.\n - `'signed_max_positive_centered'`: same as above, but scales \n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5.\n - `'signed_sum'`: scales the positive attributions such that \n they sum to 1 and the negative attributions such that they\n scale to -1. If this option is used, each channel is \n normalized separately.\n - `'01'`: normalizes the attributions to the range [0, 1] by \n subtracting the minimum attribution value then dividing by the\n maximum attribution value.\n - `'unnormalized'`: leaves the attributions unaffected.\n\n If `None`, defaults to the value supplied to the constructor.\n\n blur:\n Gives the radius of a Gaussian blur to be applied to the \n attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels. If\n `None`, defaults to the value supplied to the constructor.\n\n cmap: matplotlib.colors.Colormap | str, optional\n Colormap or name of a Colormap to use for the visualization. If\n `None`, defaults to the value supplied to the constructor.\n\n Returns:\n A `np.ndarray` array of the numerical representation of the\n attributions as modified for the visualization. This includes \n normalization, blurring, etc.\n \"\"\"\n _, normalization_type, blur, cmap = self._check_args(\n attributions, None, normalization_type, blur, cmap\n )\n\n # Combine the channels.\n attributions = attributions.mean(\n axis=get_backend().channel_axis, keepdims=True\n )\n\n # Blur the attributions so the explanation is smoother.\n if blur:\n attributions = self._blur(attributions, blur)\n\n # Normalize the attributions.\n attributions = self._normalize(attributions, normalization_type)\n\n tiled_attributions = self.tiler.tile(attributions)\n\n # Normalize the pixels to be in the range [0, 1].\n x = self._normalize(x, '01')\n tiled_x = self.tiler.tile(x)\n\n if cmap is None:\n cmap = self.default_cmap\n\n if overlay_opacity is None:\n overlay_opacity = self.default_overlay_opacity\n\n # Display the figure:\n _fig = plt.figure() if fig is None else fig\n\n plt.axis('off')\n plt.imshow(tiled_x)\n plt.imshow(tiled_attributions, alpha=overlay_opacity, cmap=cmap)\n\n if output_file:\n plt.savefig(output_file, bbox_inches=0)\n\n if imshow:\n plt.show()\n\n elif fig is None:\n plt.close(_fig)\n\n return tiled_attributions if return_tiled else attributions\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.HeatmapVisualizer.__init__","title":"
__init__(overlay_opacity=0.5, normalization_type=None, blur=10.0, cmap='jet')","text":"
Configures the default parameters for the __call__ method (these can be overridden by passing in values to __call__).
Parameters:
Name Type Description Default
overlay_opacity float Value in the range [0, 1] specifying the opacity for the heatmap overlay.
0.5 normalization_type Specifies one of the following configurations for normalizing the attributions (each item is normalized separately):
'unsigned_max': normalizes the attributions to the range [-1, 1] by dividing the attributions by the maximum absolute attribution value.'unsigned_max_positive_centered': same as above, but scales the values to the range [0, 1], with negative scores less than 0.5 and positive scores greater than 0.5. 'magnitude_max': takes the absolute value of the attributions, then normalizes the attributions to the range [0, 1] by dividing by the maximum absolute attribution value.'magnitude_sum': takes the absolute value of the attributions, then scales them such that they sum to 1. If this option is used, each channel is normalized separately, such that each channel sums to 1.'signed_max': normalizes the attributions to the range [-1, 1] by dividing the positive values by the maximum positive attribution value and the negative values by the minimum negative attribution value.'signed_max_positive_centered': same as above, but scales the values to the range [0, 1], with negative scores less than 0.5 and positive scores greater than 0.5.'signed_sum': scales the positive attributions such that they sum to 1 and the negative attributions such that they scale to -1. If this option is used, each channel is normalized separately.'01': normalizes the attributions to the range [0, 1] by subtracting the minimum attribution value then dividing by the maximum attribution value.'unnormalized': leaves the attributions unaffected.
If None, either 'unsigned_max' (for single-channel data) or 'unsigned_max_positive_centered' (for multi-channel data) is used.
None blur Gives the radius of a Gaussian blur to be applied to the attributions before visualizing. This can be used to help focus on salient regions rather than specific salient pixels.
10.0 cmap matplotlib.colors.Colormap | str, optional Colormap or name of a Colormap to use for the visualization. If None, the colormap will be chosen based on the normalization type. This argument is only used for single-channel data (including when combine_channels is True).
'jet' Source code in
trulens_explain/trulens/visualizations.py def __init__(\n self,\n overlay_opacity=0.5,\n normalization_type=None,\n blur=10.,\n cmap='jet'\n):\n \"\"\"\n Configures the default parameters for the `__call__` method (these can \n be overridden by passing in values to `__call__`).\n\n Parameters:\n overlay_opacity: float\n Value in the range [0, 1] specifying the opacity for the heatmap\n overlay.\n\n normalization_type:\n Specifies one of the following configurations for normalizing\n the attributions (each item is normalized separately):\n\n - `'unsigned_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the attributions by the maximum absolute \n attribution value.\n - `'unsigned_max_positive_centered'`: same as above, but scales\n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5. \n - `'magnitude_max'`: takes the absolute value of the \n attributions, then normalizes the attributions to the range \n [0, 1] by dividing by the maximum absolute attribution value.\n - `'magnitude_sum'`: takes the absolute value of the \n attributions, then scales them such that they sum to 1. If \n this option is used, each channel is normalized separately, \n such that each channel sums to 1.\n - `'signed_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the positive values by the maximum \n positive attribution value and the negative values by the \n minimum negative attribution value.\n - `'signed_max_positive_centered'`: same as above, but scales \n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5.\n - `'signed_sum'`: scales the positive attributions such that \n they sum to 1 and the negative attributions such that they\n scale to -1. If this option is used, each channel is \n normalized separately.\n - `'01'`: normalizes the attributions to the range [0, 1] by \n subtracting the minimum attribution value then dividing by the\n maximum attribution value.\n - `'unnormalized'`: leaves the attributions unaffected.\n\n If `None`, either `'unsigned_max'` (for single-channel data) or \n `'unsigned_max_positive_centered'` (for multi-channel data) is\n used.\n\n blur:\n Gives the radius of a Gaussian blur to be applied to the \n attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels.\n\n cmap: matplotlib.colors.Colormap | str, optional\n Colormap or name of a Colormap to use for the visualization. If \n `None`, the colormap will be chosen based on the normalization \n type. This argument is only used for single-channel data\n (including when `combine_channels` is True).\n \"\"\"\n\n super().__init__(\n combine_channels=True,\n normalization_type=normalization_type,\n blur=blur,\n cmap=cmap\n )\n\n self.default_overlay_opacity = overlay_opacity\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.IPython","title":"
IPython","text":"
Bases: HTML
Interactive python visualization output format.
Source code in
trulens_explain/trulens/visualizations.py class IPython(HTML):\n \"\"\"Interactive python visualization output format.\"\"\"\n\n def __init__(self):\n super(IPython, self).__init__()\n try:\n self.m_ipy = importlib.import_module(\"IPython\")\n except:\n raise ImportError(\n \"Jupyter output requires IPython python module. Try 'pip install ipykernel'.\"\n )\n\n def render(self, s: str):\n html = HTML.render(self, s)\n return self.m_ipy.display.HTML(html)\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.MaskVisualizer","title":"
MaskVisualizer","text":"
Bases: object
Visualizes attributions by masking the original image to highlight the regions with influence above a given threshold percentile. Intended particularly for use with input-attributions.
Source code in
trulens_explain/trulens/visualizations.py class MaskVisualizer(object):\n \"\"\"\n Visualizes attributions by masking the original image to highlight the\n regions with influence above a given threshold percentile. Intended \n particularly for use with input-attributions.\n \"\"\"\n\n def __init__(\n self,\n blur=5.,\n threshold=0.5,\n masked_opacity=0.2,\n combine_channels=True,\n use_attr_as_opacity=False,\n positive_only=True\n ):\n \"\"\"\n Configures the default parameters for the `__call__` method (these can \n be overridden by passing in values to `__call__`).\n\n Parameters:\n blur:\n Gives the radius of a Gaussian blur to be applied to the \n attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels.\n\n threshold:\n Value in the range [0, 1]. Attribution values at or below the \n percentile given by `threshold` (after normalization, blurring,\n etc.) will be masked.\n\n masked_opacity: \n Value in the range [0, 1] specifying the opacity for the parts\n of the image that are masked.\n\n combine_channels:\n If `True`, the attributions will be averaged across the channel\n dimension, resulting in a 1-channel attribution map.\n\n use_attr_as_opacity:\n If `True`, instead of using `threshold` and `masked_opacity`,\n the opacity of each pixel is given by the 0-1-normalized \n attribution value.\n\n positive_only:\n If `True`, only pixels with positive attribution will be \n unmasked (or given nonzero opacity when `use_attr_as_opacity` is\n true).\n \"\"\"\n\n self.default_blur = blur\n self.default_thresh = threshold\n self.default_masked_opacity = masked_opacity\n self.default_combine_channels = combine_channels\n\n # TODO(klas): in the future we can allow configuring of tiling settings\n # by allowing the user to specify the tiler.\n self.tiler = Tiler()\n\n def __call__(\n self,\n attributions,\n x,\n output_file=None,\n imshow=True,\n fig=None,\n return_tiled=True,\n blur=None,\n threshold=None,\n masked_opacity=None,\n combine_channels=None,\n use_attr_as_opacity=None,\n positive_only=None\n ):\n channel_axis = get_backend().channel_axis\n if attributions.shape != x.shape:\n raise ValueError(\n 'Shape of `attributions` {} must match shape of `x` {}'.format(\n attributions.shape, x.shape\n )\n )\n\n if blur is None:\n blur = self.default_blur\n\n if threshold is None:\n threshold = self.default_thresh\n\n if masked_opacity is None:\n masked_opacity = self.default_masked_opacity\n\n if combine_channels is None:\n combine_channels = self.default_combine_channels\n\n if len(attributions.shape) != 4:\n raise ValueError(\n '`MaskVisualizer` is inteded for 4-D image-format data. Given '\n 'input with dimension {}'.format(len(attributions.shape))\n )\n\n if combine_channels is None:\n combine_channels = self.default_combine_channels\n\n if combine_channels:\n attributions = attributions.mean(axis=channel_axis, keepdims=True)\n\n if x.shape[channel_axis] not in (1, 3, 4):\n raise ValueError(\n 'To visualize, attributions must have either 1, 3, or 4 color '\n 'channels, but Visualizer got {} channels.\\n'\n 'If you are visualizing an internal layer, consider setting '\n '`combine_channels` to True'.format(\n attributions.shape[channel_axis]\n )\n )\n\n # Blur the attributions so the explanation is smoother.\n if blur is not None:\n attributions = [gaussian_filter(a, blur) for a in attributions]\n\n # If `positive_only` clip attributions.\n if positive_only:\n attributions = np.maximum(attributions, 0)\n\n # Normalize the attributions to be in the range [0, 1].\n attributions = [a - a.min() for a in attributions]\n attributions = [\n 0. * a if a.max() == 0. else a / a.max() for a in attributions\n ]\n\n # Normalize the pixels to be in the range [0, 1]\n x = [xc - xc.min() for xc in x]\n x = np.array([0. * xc if xc.max() == 0. else xc / xc.max() for xc in x])\n\n # Threshold the attributions to create a mask.\n if threshold is not None:\n percentiles = [\n np.percentile(a, 100 * threshold) for a in attributions\n ]\n masks = np.array(\n [\n np.maximum(a > p, masked_opacity)\n for a, p in zip(attributions, percentiles)\n ]\n )\n\n else:\n masks = np.array(attributions)\n\n # Use the mask on the original image to visualize the explanation.\n attributions = masks * x\n tiled_attributions = self.tiler.tile(attributions)\n\n if imshow:\n plt.axis('off')\n plt.imshow(tiled_attributions)\n\n if output_file:\n plt.savefig(output_file, bbox_inches=0)\n\n return tiled_attributions if return_tiled else attributions\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.MaskVisualizer.__init__","title":"
__init__(blur=5.0, threshold=0.5, masked_opacity=0.2, combine_channels=True, use_attr_as_opacity=False, positive_only=True)","text":"
Configures the default parameters for the __call__ method (these can be overridden by passing in values to __call__).
Parameters:
Name Type Description Default
blur Gives the radius of a Gaussian blur to be applied to the attributions before visualizing. This can be used to help focus on salient regions rather than specific salient pixels.
5.0 threshold Value in the range [0, 1]. Attribution values at or below the percentile given by threshold (after normalization, blurring, etc.) will be masked.
0.5 masked_opacity Value in the range [0, 1] specifying the opacity for the parts of the image that are masked.
0.2 combine_channels If True, the attributions will be averaged across the channel dimension, resulting in a 1-channel attribution map.
True use_attr_as_opacity If True, instead of using threshold and masked_opacity, the opacity of each pixel is given by the 0-1-normalized attribution value.
False positive_only If True, only pixels with positive attribution will be unmasked (or given nonzero opacity when use_attr_as_opacity is true).
True Source code in
trulens_explain/trulens/visualizations.py def __init__(\n self,\n blur=5.,\n threshold=0.5,\n masked_opacity=0.2,\n combine_channels=True,\n use_attr_as_opacity=False,\n positive_only=True\n):\n \"\"\"\n Configures the default parameters for the `__call__` method (these can \n be overridden by passing in values to `__call__`).\n\n Parameters:\n blur:\n Gives the radius of a Gaussian blur to be applied to the \n attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels.\n\n threshold:\n Value in the range [0, 1]. Attribution values at or below the \n percentile given by `threshold` (after normalization, blurring,\n etc.) will be masked.\n\n masked_opacity: \n Value in the range [0, 1] specifying the opacity for the parts\n of the image that are masked.\n\n combine_channels:\n If `True`, the attributions will be averaged across the channel\n dimension, resulting in a 1-channel attribution map.\n\n use_attr_as_opacity:\n If `True`, instead of using `threshold` and `masked_opacity`,\n the opacity of each pixel is given by the 0-1-normalized \n attribution value.\n\n positive_only:\n If `True`, only pixels with positive attribution will be \n unmasked (or given nonzero opacity when `use_attr_as_opacity` is\n true).\n \"\"\"\n\n self.default_blur = blur\n self.default_thresh = threshold\n self.default_masked_opacity = masked_opacity\n self.default_combine_channels = combine_channels\n\n # TODO(klas): in the future we can allow configuring of tiling settings\n # by allowing the user to specify the tiler.\n self.tiler = Tiler()\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.NLP","title":"
NLP","text":"
Bases: object
NLP Visualization tools.
Source code in
trulens_explain/trulens/visualizations.py class NLP(object):\n \"\"\"NLP Visualization tools.\"\"\"\n\n # Batches of text inputs not yet tokenized.\n TextBatch = TypeVar(\"TextBatch\")\n\n # Inputs that are directly accepted by wrapped models, tokenized.\n # TODO(piotrm): Reuse other typevars/aliases from elsewhere.\n ModelInput = TypeVar(\"ModelInput\")\n\n # Outputs produced by wrapped models.\n # TODO(piotrm): Reuse other typevars/aliases from elsewhere.\n ModelOutput = TypeVar(\"ModelOutput\")\n\n def __init__(\n self,\n wrapper: ModelWrapper,\n output: Optional[Output] = None,\n labels: Optional[Iterable[str]] = None,\n tokenize: Optional[Callable[[TextBatch], ModelInputs]] = None,\n decode: Optional[Callable[[Tensor], str]] = None,\n input_accessor: Optional[Callable[[ModelInputs],\n Iterable[Tensor]]] = None,\n output_accessor: Optional[Callable[[ModelOutput],\n Iterable[Tensor]]] = None,\n attr_aggregate: Optional[Callable[[Tensor], Tensor]] = None,\n hidden_tokens: Optional[Set[int]] = set()\n ):\n \"\"\"Initializate NLP visualization tools for a given environment.\n\n Parameters:\n wrapper: ModelWrapper\n The wrapped model whose channel we're visualizing.\n\n output: Output, optional\n Visualization output format. Defaults to PlainText unless\n ipython is detected and in which case defaults to IPython\n format.\n\n labels: Iterable[str], optional\n Names of prediction classes for classification models.\n\n tokenize: Callable[[TextBatch], ModelInput], optional\n Method to tokenize an instance.\n\n decode: Callable[[Tensor], str], optional\n Method to invert/decode the tokenization.\n\n input_accessor: Callable[[ModelInputs], Iterable[Tensor]], optional\n Method to extract input/token ids from model inputs (tokenize\n output) if needed.\n\n output_accessor: Callable[[ModelOutput], Iterable[Tensor]], optional\n Method to extract outout logits from output structures if\n needed.\n\n attr_aggregate: Callable[[Tensor], Tensor], optional\n Method to aggregate attribution for embedding into a single\n value. Defaults to sum.\n\n hidden_tokens: Set[int], optional\n For token-based visualizations, which tokens to hide.\n \"\"\"\n if output is None:\n try:\n # check if running in interactive python (jupyer, colab, etc) to\n # use appropriate output format\n get_ipython()\n output = IPython()\n\n except NameError:\n output = PlainText()\n tru_logger(\n \"WARNING: could not guess preferred visualization output format, using PlainText\"\n )\n\n # TODO: automatic inference of various parameters for common repositories like huggingface, tfhub.\n\n self.output = output\n self.labels = labels\n self.tokenize = tokenize\n self.decode = decode\n self.wrapper = wrapper\n\n self.input_accessor = input_accessor # could be inferred\n self.output_accessor = output_accessor # could be inferred\n\n B = get_backend()\n\n if attr_aggregate is None:\n attr_aggregate = B.sum\n\n self.attr_aggregate = attr_aggregate\n\n self.hidden_tokens = hidden_tokens\n\n def token_attribution(self, texts: Iterable[str], attr: AttributionMethod):\n \"\"\"Visualize a token-based input attribution on given `texts` inputs via the attribution method `attr`.\n\n Parameters:\n texts: Iterable[str]\n The input texts to visualize.\n\n attr: AttributionMethod\n The attribution method to generate the token importances with.\n\n Returns: Any\n The visualization in the format specified by this class's `output` parameter.\n \"\"\"\n\n B = get_backend()\n\n if self.tokenize is None:\n return ValueError(\"tokenize not provided to NLP visualizer.\")\n\n inputs = self.tokenize(texts)\n\n outputs = inputs.call_on(self.wrapper._model)\n attrs = inputs.call_on(attr.attributions)\n\n content = self.output.blank()\n\n input_ids = inputs\n if self.input_accessor is not None:\n input_ids = self.input_accessor(inputs)\n\n if (not isinstance(input_ids, Iterable)) or isinstance(input_ids, dict):\n raise ValueError(\n f\"Inputs ({input_ids.__class__.__name__}) need to be iterable over instances. You might need to set input_accessor.\"\n )\n\n output_logits = outputs\n if self.output_accessor is not None:\n output_logits = self.output_accessor(outputs)\n\n if (not isinstance(output_logits, Iterable)) or isinstance(\n output_logits, dict):\n raise ValueError(\n f\"Outputs ({output_logits.__class__.__name__}) need to be iterable over instances. You might need to set output_accessor.\"\n )\n\n for i, (sentence_word_id, attr,\n logits) in enumerate(zip(input_ids, attrs, output_logits)):\n\n logits = logits.to('cpu').detach().numpy()\n pred = logits.argmax()\n\n if self.labels is not None:\n pred_name = self.labels[pred]\n else:\n pred_name = str(pred)\n\n sent = self.output.append(\n self.output.escape(pred_name), \":\", self.output.space()\n )\n\n for word_id, attr in zip(sentence_word_id, attr):\n word_id = int(B.as_array(word_id))\n\n if word_id in self.hidden_tokens:\n continue\n\n if self.decode is not None:\n word = self.decode(word_id)\n else:\n word = str(word_id)\n\n mag = self.attr_aggregate(attr)\n\n if word[0] == ' ':\n word = word[1:]\n sent = self.output.append(sent, self.output.space())\n\n sent = self.output.append(\n sent,\n self.output.magnitude_colored(\n self.output.escape(word), mag\n )\n )\n\n content = self.output.append(\n content, self.output.line(sent), self.output.linebreak(),\n self.output.linebreak()\n )\n\n return self.output.render(content)\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.NLP.__init__","title":"
__init__(wrapper, output=None, labels=None, tokenize=None, decode=None, input_accessor=None, output_accessor=None, attr_aggregate=None, hidden_tokens=set())","text":"
Initializate NLP visualization tools for a given environment.
Parameters:
Name Type Description Default
wrapper ModelWrapper ModelWrapper The wrapped model whose channel we're visualizing.
required
output Optional[Output] Output, optional Visualization output format. Defaults to PlainText unless ipython is detected and in which case defaults to IPython format.
None labels Optional[Iterable[str]] Iterable[str], optional Names of prediction classes for classification models.
None tokenize Optional[Callable[[TextBatch], ModelInputs]] Callable[[TextBatch], ModelInput], optional Method to tokenize an instance.
None decode Optional[Callable[[Tensor], str]] Callable[[Tensor], str], optional Method to invert/decode the tokenization.
None input_accessor Optional[Callable[[ModelInputs], Iterable[Tensor]]] Callable[[ModelInputs], Iterable[Tensor]], optional Method to extract input/token ids from model inputs (tokenize output) if needed.
None output_accessor Optional[Callable[[ModelOutput], Iterable[Tensor]]] Callable[[ModelOutput], Iterable[Tensor]], optional Method to extract outout logits from output structures if needed.
None attr_aggregate Optional[Callable[[Tensor], Tensor]] Callable[[Tensor], Tensor], optional Method to aggregate attribution for embedding into a single value. Defaults to sum.
None hidden_tokens Optional[Set[int]] Set[int], optional For token-based visualizations, which tokens to hide.
set() Source code in
trulens_explain/trulens/visualizations.py def __init__(\n self,\n wrapper: ModelWrapper,\n output: Optional[Output] = None,\n labels: Optional[Iterable[str]] = None,\n tokenize: Optional[Callable[[TextBatch], ModelInputs]] = None,\n decode: Optional[Callable[[Tensor], str]] = None,\n input_accessor: Optional[Callable[[ModelInputs],\n Iterable[Tensor]]] = None,\n output_accessor: Optional[Callable[[ModelOutput],\n Iterable[Tensor]]] = None,\n attr_aggregate: Optional[Callable[[Tensor], Tensor]] = None,\n hidden_tokens: Optional[Set[int]] = set()\n):\n \"\"\"Initializate NLP visualization tools for a given environment.\n\n Parameters:\n wrapper: ModelWrapper\n The wrapped model whose channel we're visualizing.\n\n output: Output, optional\n Visualization output format. Defaults to PlainText unless\n ipython is detected and in which case defaults to IPython\n format.\n\n labels: Iterable[str], optional\n Names of prediction classes for classification models.\n\n tokenize: Callable[[TextBatch], ModelInput], optional\n Method to tokenize an instance.\n\n decode: Callable[[Tensor], str], optional\n Method to invert/decode the tokenization.\n\n input_accessor: Callable[[ModelInputs], Iterable[Tensor]], optional\n Method to extract input/token ids from model inputs (tokenize\n output) if needed.\n\n output_accessor: Callable[[ModelOutput], Iterable[Tensor]], optional\n Method to extract outout logits from output structures if\n needed.\n\n attr_aggregate: Callable[[Tensor], Tensor], optional\n Method to aggregate attribution for embedding into a single\n value. Defaults to sum.\n\n hidden_tokens: Set[int], optional\n For token-based visualizations, which tokens to hide.\n \"\"\"\n if output is None:\n try:\n # check if running in interactive python (jupyer, colab, etc) to\n # use appropriate output format\n get_ipython()\n output = IPython()\n\n except NameError:\n output = PlainText()\n tru_logger(\n \"WARNING: could not guess preferred visualization output format, using PlainText\"\n )\n\n # TODO: automatic inference of various parameters for common repositories like huggingface, tfhub.\n\n self.output = output\n self.labels = labels\n self.tokenize = tokenize\n self.decode = decode\n self.wrapper = wrapper\n\n self.input_accessor = input_accessor # could be inferred\n self.output_accessor = output_accessor # could be inferred\n\n B = get_backend()\n\n if attr_aggregate is None:\n attr_aggregate = B.sum\n\n self.attr_aggregate = attr_aggregate\n\n self.hidden_tokens = hidden_tokens\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.NLP.token_attribution","title":"
token_attribution(texts, attr)","text":"
Visualize a token-based input attribution on given texts inputs via the attribution method attr.
Parameters:
Name Type Description Default
texts Iterable[str] Iterable[str] The input texts to visualize.
required
attr AttributionMethod AttributionMethod The attribution method to generate the token importances with.
required
Any
Type Description
The visualization in the format specified by this class's output parameter.
Source code in
trulens_explain/trulens/visualizations.py def token_attribution(self, texts: Iterable[str], attr: AttributionMethod):\n \"\"\"Visualize a token-based input attribution on given `texts` inputs via the attribution method `attr`.\n\n Parameters:\n texts: Iterable[str]\n The input texts to visualize.\n\n attr: AttributionMethod\n The attribution method to generate the token importances with.\n\n Returns: Any\n The visualization in the format specified by this class's `output` parameter.\n \"\"\"\n\n B = get_backend()\n\n if self.tokenize is None:\n return ValueError(\"tokenize not provided to NLP visualizer.\")\n\n inputs = self.tokenize(texts)\n\n outputs = inputs.call_on(self.wrapper._model)\n attrs = inputs.call_on(attr.attributions)\n\n content = self.output.blank()\n\n input_ids = inputs\n if self.input_accessor is not None:\n input_ids = self.input_accessor(inputs)\n\n if (not isinstance(input_ids, Iterable)) or isinstance(input_ids, dict):\n raise ValueError(\n f\"Inputs ({input_ids.__class__.__name__}) need to be iterable over instances. You might need to set input_accessor.\"\n )\n\n output_logits = outputs\n if self.output_accessor is not None:\n output_logits = self.output_accessor(outputs)\n\n if (not isinstance(output_logits, Iterable)) or isinstance(\n output_logits, dict):\n raise ValueError(\n f\"Outputs ({output_logits.__class__.__name__}) need to be iterable over instances. You might need to set output_accessor.\"\n )\n\n for i, (sentence_word_id, attr,\n logits) in enumerate(zip(input_ids, attrs, output_logits)):\n\n logits = logits.to('cpu').detach().numpy()\n pred = logits.argmax()\n\n if self.labels is not None:\n pred_name = self.labels[pred]\n else:\n pred_name = str(pred)\n\n sent = self.output.append(\n self.output.escape(pred_name), \":\", self.output.space()\n )\n\n for word_id, attr in zip(sentence_word_id, attr):\n word_id = int(B.as_array(word_id))\n\n if word_id in self.hidden_tokens:\n continue\n\n if self.decode is not None:\n word = self.decode(word_id)\n else:\n word = str(word_id)\n\n mag = self.attr_aggregate(attr)\n\n if word[0] == ' ':\n word = word[1:]\n sent = self.output.append(sent, self.output.space())\n\n sent = self.output.append(\n sent,\n self.output.magnitude_colored(\n self.output.escape(word), mag\n )\n )\n\n content = self.output.append(\n content, self.output.line(sent), self.output.linebreak(),\n self.output.linebreak()\n )\n\n return self.output.render(content)\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.Output","title":"
Output","text":"
Bases: ABC
Base class for visualization output formats.
Source code in
trulens_explain/trulens/visualizations.py class Output(ABC):\n \"\"\"Base class for visualization output formats.\"\"\"\n\n @abstractmethod\n def blank(self) -> str:\n ...\n\n @abstractmethod\n def space(self) -> str:\n ...\n\n @abstractmethod\n def escape(self, s: str) -> str:\n ...\n\n @abstractmethod\n def line(self, s: str) -> str:\n ...\n\n @abstractmethod\n def magnitude_colored(self, s: str, mag: float) -> str:\n ...\n\n @abstractmethod\n def append(self, *parts: Iterable[str]) -> str:\n ...\n\n @abstractmethod\n def render(self, s: str) -> str:\n ...\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.PlainText","title":"
PlainText","text":"
Bases: Output
Plain text visualization output format.
Source code in
trulens_explain/trulens/visualizations.py class PlainText(Output):\n \"\"\"Plain text visualization output format.\"\"\"\n\n def blank(self):\n return \"\"\n\n def space(self):\n return \" \"\n\n def escape(self, s):\n return s\n\n def line(self, s):\n return s\n\n def magnitude_colored(self, s, mag):\n return f\"{s}({mag:0.3f})\"\n\n def append(self, *parts):\n return ''.join(parts)\n\n def render(self, s):\n return s\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.Tiler","title":"
Tiler","text":"
Bases: object
Used to tile batched images or attributions.
Source code in
trulens_explain/trulens/visualizations.py class Tiler(object):\n \"\"\"\n Used to tile batched images or attributions.\n \"\"\"\n\n def tile(self, a: np.ndarray) -> np.ndarray:\n \"\"\"\n Tiles the given array into a grid that is as square as possible.\n\n Parameters:\n a:\n An array of 4D batched image data.\n\n Returns:\n A tiled array of the images from `a`. The resulting array has rank\n 3 for color images, and 2 for grayscale images (the batch dimension\n is removed, as well as the channel dimension for grayscale images).\n The resulting array has its color channel dimension ordered last to\n fit the requirements of the `matplotlib` library.\n \"\"\"\n\n # `pyplot` expects the channels to come last.\n if get_backend().dim_order == 'channels_first':\n a = a.transpose((0, 2, 3, 1))\n\n n, h, w, c = a.shape\n\n rows = int(np.sqrt(n))\n cols = int(np.ceil(float(n) / rows))\n\n new_a = np.zeros((h * rows, w * cols, c))\n\n for i, x in enumerate(a):\n row = i // cols\n col = i % cols\n new_a[row * h:(row + 1) * h, col * w:(col + 1) * w] = x\n\n return np.squeeze(new_a)\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.Tiler.tile","title":"
tile(a)","text":"
Tiles the given array into a grid that is as square as possible.
Parameters:
Name Type Description Default
a ndarray An array of 4D batched image data.
required
Returns:
Type Description
ndarray A tiled array of the images from a. The resulting array has rank
ndarray 3 for color images, and 2 for grayscale images (the batch dimension
ndarray is removed, as well as the channel dimension for grayscale images).
ndarray The resulting array has its color channel dimension ordered last to
ndarray fit the requirements of the matplotlib library.
Source code in
trulens_explain/trulens/visualizations.py def tile(self, a: np.ndarray) -> np.ndarray:\n \"\"\"\n Tiles the given array into a grid that is as square as possible.\n\n Parameters:\n a:\n An array of 4D batched image data.\n\n Returns:\n A tiled array of the images from `a`. The resulting array has rank\n 3 for color images, and 2 for grayscale images (the batch dimension\n is removed, as well as the channel dimension for grayscale images).\n The resulting array has its color channel dimension ordered last to\n fit the requirements of the `matplotlib` library.\n \"\"\"\n\n # `pyplot` expects the channels to come last.\n if get_backend().dim_order == 'channels_first':\n a = a.transpose((0, 2, 3, 1))\n\n n, h, w, c = a.shape\n\n rows = int(np.sqrt(n))\n cols = int(np.ceil(float(n) / rows))\n\n new_a = np.zeros((h * rows, w * cols, c))\n\n for i, x in enumerate(a):\n row = i // cols\n col = i % cols\n new_a[row * h:(row + 1) * h, col * w:(col + 1) * w] = x\n\n return np.squeeze(new_a)\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.Visualizer","title":"
Visualizer","text":"
Bases: object
Visualizes attributions directly as a color image. Intended particularly for use with input-attributions.
This can also be used for viewing images (rather than attributions).
Source code in
trulens_explain/trulens/visualizations.py class Visualizer(object):\n \"\"\"\n Visualizes attributions directly as a color image. Intended particularly for\n use with input-attributions.\n\n This can also be used for viewing images (rather than attributions).\n \"\"\"\n\n def __init__(\n self,\n combine_channels: bool = False,\n normalization_type: str = None,\n blur: float = 0.,\n cmap: Colormap = None\n ):\n \"\"\"\n Configures the default parameters for the `__call__` method (these can \n be overridden by passing in values to `__call__`).\n\n Parameters:\n combine_channels:\n If `True`, the attributions will be averaged across the channel\n dimension, resulting in a 1-channel attribution map.\n\n normalization_type:\n Specifies one of the following configurations for normalizing\n the attributions (each item is normalized separately):\n\n - `'unsigned_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the attributions by the maximum absolute \n attribution value.\n - `'unsigned_max_positive_centered'`: same as above, but scales\n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5. \n - `'magnitude_max'`: takes the absolute value of the \n attributions, then normalizes the attributions to the range \n [0, 1] by dividing by the maximum absolute attribution value.\n - `'magnitude_sum'`: takes the absolute value of the \n attributions, then scales them such that they sum to 1. If \n this option is used, each channel is normalized separately, \n such that each channel sums to 1.\n - `'signed_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the positive values by the maximum \n positive attribution value and the negative values by the \n minimum negative attribution value.\n - `'signed_max_positive_centered'`: same as above, but scales \n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5.\n - `'signed_sum'`: scales the positive attributions such that \n they sum to 1 and the negative attributions such that they\n scale to -1. If this option is used, each channel is \n normalized separately.\n - `'01'`: normalizes the attributions to the range [0, 1] by \n subtracting the minimum attribution value then dividing by the\n maximum attribution value.\n - `'unnormalized'`: leaves the attributions unaffected.\n\n If `None`, either `'unsigned_max'` (for single-channel data) or \n `'unsigned_max_positive_centered'` (for multi-channel data) is\n used.\n\n blur:\n Gives the radius of a Gaussian blur to be applied to the \n attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels.\n\n cmap: matplotlib.colors.Colormap | str, optional\n Colormap or name of a Colormap to use for the visualization. If \n `None`, the colormap will be chosen based on the normalization \n type. This argument is only used for single-channel data\n (including when `combine_channels` is True).\n \"\"\"\n self.default_combine_channels = combine_channels\n self.default_normalization_type = normalization_type\n self.default_blur = blur\n self.default_cmap = cmap if cmap is not None else self._get_hotcold()\n\n # TODO(klas): in the future we can allow configuring of tiling settings\n # by allowing the user to specify the tiler.\n self.tiler = Tiler()\n\n def __call__(\n self,\n attributions,\n output_file=None,\n imshow=True,\n fig=None,\n return_tiled=False,\n combine_channels=None,\n normalization_type=None,\n blur=None,\n cmap=None\n ) -> np.ndarray:\n \"\"\"\n Visualizes the given attributions.\n\n Parameters:\n attributions:\n A `np.ndarray` containing the attributions to be visualized.\n\n output_file:\n File name to save the visualization image to. If `None`, no\n image will be saved, but the figure can still be displayed.\n\n imshow:\n If true, a the visualization will be displayed. Otherwise the\n figure will not be displayed, but the figure can still be saved.\n\n fig:\n The `pyplot` figure to display the visualization in. If `None`,\n a new figure will be created.\n\n return_tiled:\n If true, the returned array will be in the same shape as the\n visualization, with no batch dimension and the samples in the\n batch tiled along the width and height dimensions. If false, the\n returned array will be reshaped to match `attributions`.\n\n combine_channels:\n If `True`, the attributions will be averaged across the channel\n dimension, resulting in a 1-channel attribution map. If `None`,\n defaults to the value supplied to the constructor.\n\n normalization_type:\n Specifies one of the following configurations for normalizing\n the attributions (each item is normalized separately):\n\n - `'unsigned_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the attributions by the maximum absolute \n attribution value.\n - `'unsigned_max_positive_centered'`: same as above, but scales\n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5. \n - `'magnitude_max'`: takes the absolute value of the \n attributions, then normalizes the attributions to the range \n [0, 1] by dividing by the maximum absolute attribution value.\n - `'magnitude_sum'`: takes the absolute value of the \n attributions, then scales them such that they sum to 1. If \n this option is used, each channel is normalized separately, \n such that each channel sums to 1.\n - `'signed_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the positive values by the maximum \n positive attribution value and the negative values by the \n minimum negative attribution value.\n - `'signed_max_positive_centered'`: same as above, but scales \n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5.\n - `'signed_sum'`: scales the positive attributions such that \n they sum to 1 and the negative attributions such that they\n scale to -1. If this option is used, each channel is \n normalized separately.\n - `'01'`: normalizes the attributions to the range [0, 1] by \n subtracting the minimum attribution value then dividing by the\n maximum attribution value.\n - `'unnormalized'`: leaves the attributions unaffected.\n\n If `None`, defaults to the value supplied to the constructor.\n\n blur:\n Gives the radius of a Gaussian blur to be applied to the \n attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels. If\n `None`, defaults to the value supplied to the constructor.\n\n cmap: matplotlib.colors.Colormap | str, optional\n Colormap or name of a Colormap to use for the visualization. If\n `None`, defaults to the value supplied to the constructor.\n\n Returns:\n A `np.ndarray` array of the numerical representation of the\n attributions as modified for the visualization. This includes \n normalization, blurring, etc.\n \"\"\"\n combine_channels, normalization_type, blur, cmap = self._check_args(\n attributions, combine_channels, normalization_type, blur, cmap\n )\n\n # Combine the channels if specified.\n if combine_channels:\n attributions = attributions.mean(\n axis=get_backend().channel_axis, keepdims=True\n )\n\n # Blur the attributions so the explanation is smoother.\n if blur:\n attributions = self._blur(attributions, blur)\n\n # Normalize the attributions.\n attributions = self._normalize(attributions, normalization_type)\n\n tiled_attributions = self.tiler.tile(attributions)\n\n # Display the figure:\n _fig = plt.figure() if fig is None else fig\n\n plt.axis('off')\n plt.imshow(tiled_attributions, cmap=cmap)\n\n if output_file:\n plt.savefig(output_file, bbox_inches=0)\n\n if imshow:\n plt.show()\n\n elif fig is None:\n plt.close(_fig)\n\n return tiled_attributions if return_tiled else attributions\n\n def _check_args(\n self, attributions, combine_channels, normalization_type, blur, cmap\n ):\n \"\"\"\n Validates the arguments, and sets them to their default values if they\n are not specified.\n \"\"\"\n if attributions.ndim != 4:\n raise ValueError(\n '`Visualizer` is inteded for 4-D image-format data. Given '\n 'input with dimension {}'.format(attributions.ndim)\n )\n\n if combine_channels is None:\n combine_channels = self.default_combine_channels\n\n channel_axis = get_backend().channel_axis\n if not (attributions.shape[channel_axis] in (1, 3, 4) or\n combine_channels):\n\n raise ValueError(\n 'To visualize, attributions must have either 1, 3, or 4 color '\n 'channels, but `Visualizer` got {} channels.\\n'\n 'If you are visualizing an internal layer, consider setting '\n '`combine_channels` to True'.format(\n attributions.shape[channel_axis]\n )\n )\n\n if normalization_type is None:\n normalization_type = self.default_normalization_type\n\n if normalization_type is None:\n if combine_channels or attributions.shape[channel_axis] == 1:\n normalization_type = 'unsigned_max'\n\n else:\n normalization_type = 'unsigned_max_positive_centered'\n\n valid_normalization_types = [\n 'unsigned_max',\n 'unsigned_max_positive_centered',\n 'magnitude_max',\n 'magnitude_sum',\n 'signed_max',\n 'signed_max_positive_centered',\n 'signed_sum',\n '01',\n 'unnormalized',\n ]\n if normalization_type not in valid_normalization_types:\n raise ValueError(\n '`norm` must be None or one of the following options:' +\n ','.join(\n [\n '\\'{}\\''.form(norm_type)\n for norm_type in valid_normalization_types\n ]\n )\n )\n\n if blur is None:\n blur = self.default_blur\n\n if cmap is None:\n cmap = self.default_cmap\n\n return combine_channels, normalization_type, blur, cmap\n\n def _normalize(self, attributions, normalization_type, eps=1e-20):\n channel_axis = get_backend().channel_axis\n if normalization_type == 'unnormalized':\n return attributions\n\n split_by_channel = normalization_type.endswith('sum')\n\n channel_split = [attributions] if split_by_channel else np.split(\n attributions, attributions.shape[channel_axis], axis=channel_axis\n )\n\n normalized_attributions = []\n for c_map in channel_split:\n if normalization_type == 'magnitude_max':\n c_map = np.abs(c_map) / (\n np.abs(c_map).max(axis=(1, 2, 3), keepdims=True) + eps\n )\n\n elif normalization_type == 'magnitude_sum':\n c_map = np.abs(c_map) / (\n np.abs(c_map).sum(axis=(1, 2, 3), keepdims=True) + eps\n )\n\n elif normalization_type.startswith('signed_max'):\n postive_max = c_map.max(axis=(1, 2, 3), keepdims=True)\n negative_max = (-c_map).max(axis=(1, 2, 3), keepdims=True)\n\n # Normalize the postive socres to [0, 1] and negative socresn to\n # [-1, 0].\n normalization_factor = np.where(\n c_map >= 0, postive_max, negative_max\n )\n c_map = c_map / (normalization_factor + eps)\n\n # If positive-centered, normalize so that all scores are in the\n # range [0, 1], with negative scores less than 0.5 and positive\n # scores greater than 0.5.\n if normalization_type.endswith('positive_centered'):\n c_map = c_map / 2. + 0.5\n\n elif normalization_type == 'signed_sum':\n postive_max = np.maximum(c_map, 0).sum(\n axis=(1, 2, 3), keepdims=True\n )\n negative_max = np.maximum(-c_map, 0).sum(\n axis=(1, 2, 3), keepdims=True\n )\n\n # Normalize the postive socres to ensure they sum to 1 and the\n # negative scores to ensure they sum to -1.\n normalization_factor = np.where(\n c_map >= 0, postive_max, negative_max\n )\n c_map = c_map / (normalization_factor + eps)\n\n elif normalization_type.startswith('unsigned_max'):\n c_map = c_map / (\n np.abs(c_map).max(axis=(1, 2, 3), keepdims=True) + eps\n )\n\n # If positive-centered, normalize so that all scores are in the\n # range [0, 1], with negative scores less than 0.5 and positive\n # scores greater than 0.5.\n if normalization_type.endswith('positive_centered'):\n c_map = c_map / 2. + 0.5\n\n elif normalization_type == '01':\n c_map = c_map - c_map.min(axis=(1, 2, 3), keepdims=True)\n c_map = c_map / (c_map.max(axis=(1, 2, 3), keepdims=True) + eps)\n\n normalized_attributions.append(c_map)\n\n return np.concatenate(normalized_attributions, axis=channel_axis)\n\n def _blur(self, attributions, blur):\n for i in range(attributions.shape[0]):\n attributions[i] = gaussian_filter(attributions[i], blur)\n\n return attributions\n\n def _get_hotcold(self):\n hot = cm.get_cmap('hot', 128)\n cool = cm.get_cmap('cool', 128)\n binary = cm.get_cmap('binary', 128)\n hotcold = np.vstack(\n (\n binary(np.linspace(0, 1, 128)) * cool(np.linspace(0, 1, 128)),\n hot(np.linspace(0, 1, 128))\n )\n )\n\n return ListedColormap(hotcold, name='hotcold')\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.Visualizer.__call__","title":"
__call__(attributions, output_file=None, imshow=True, fig=None, return_tiled=False, combine_channels=None, normalization_type=None, blur=None, cmap=None)","text":"
Visualizes the given attributions.
Parameters:
Name Type Description Default
attributions A np.ndarray containing the attributions to be visualized.
required
output_file File name to save the visualization image to. If None, no image will be saved, but the figure can still be displayed.
None imshow If true, a the visualization will be displayed. Otherwise the figure will not be displayed, but the figure can still be saved.
True fig The pyplot figure to display the visualization in. If None, a new figure will be created.
None return_tiled If true, the returned array will be in the same shape as the visualization, with no batch dimension and the samples in the batch tiled along the width and height dimensions. If false, the returned array will be reshaped to match attributions.
False combine_channels If True, the attributions will be averaged across the channel dimension, resulting in a 1-channel attribution map. If None, defaults to the value supplied to the constructor.
None normalization_type Specifies one of the following configurations for normalizing the attributions (each item is normalized separately):
'unsigned_max': normalizes the attributions to the range [-1, 1] by dividing the attributions by the maximum absolute attribution value.'unsigned_max_positive_centered': same as above, but scales the values to the range [0, 1], with negative scores less than 0.5 and positive scores greater than 0.5. 'magnitude_max': takes the absolute value of the attributions, then normalizes the attributions to the range [0, 1] by dividing by the maximum absolute attribution value.'magnitude_sum': takes the absolute value of the attributions, then scales them such that they sum to 1. If this option is used, each channel is normalized separately, such that each channel sums to 1.'signed_max': normalizes the attributions to the range [-1, 1] by dividing the positive values by the maximum positive attribution value and the negative values by the minimum negative attribution value.'signed_max_positive_centered': same as above, but scales the values to the range [0, 1], with negative scores less than 0.5 and positive scores greater than 0.5.'signed_sum': scales the positive attributions such that they sum to 1 and the negative attributions such that they scale to -1. If this option is used, each channel is normalized separately.'01': normalizes the attributions to the range [0, 1] by subtracting the minimum attribution value then dividing by the maximum attribution value.'unnormalized': leaves the attributions unaffected.
If None, defaults to the value supplied to the constructor.
None blur Gives the radius of a Gaussian blur to be applied to the attributions before visualizing. This can be used to help focus on salient regions rather than specific salient pixels. If None, defaults to the value supplied to the constructor.
None cmap matplotlib.colors.Colormap | str, optional Colormap or name of a Colormap to use for the visualization. If None, defaults to the value supplied to the constructor.
None Returns:
Type Description
ndarray A np.ndarray array of the numerical representation of the
ndarray attributions as modified for the visualization. This includes
ndarray normalization, blurring, etc.
Source code in
trulens_explain/trulens/visualizations.py def __call__(\n self,\n attributions,\n output_file=None,\n imshow=True,\n fig=None,\n return_tiled=False,\n combine_channels=None,\n normalization_type=None,\n blur=None,\n cmap=None\n) -> np.ndarray:\n \"\"\"\n Visualizes the given attributions.\n\n Parameters:\n attributions:\n A `np.ndarray` containing the attributions to be visualized.\n\n output_file:\n File name to save the visualization image to. If `None`, no\n image will be saved, but the figure can still be displayed.\n\n imshow:\n If true, a the visualization will be displayed. Otherwise the\n figure will not be displayed, but the figure can still be saved.\n\n fig:\n The `pyplot` figure to display the visualization in. If `None`,\n a new figure will be created.\n\n return_tiled:\n If true, the returned array will be in the same shape as the\n visualization, with no batch dimension and the samples in the\n batch tiled along the width and height dimensions. If false, the\n returned array will be reshaped to match `attributions`.\n\n combine_channels:\n If `True`, the attributions will be averaged across the channel\n dimension, resulting in a 1-channel attribution map. If `None`,\n defaults to the value supplied to the constructor.\n\n normalization_type:\n Specifies one of the following configurations for normalizing\n the attributions (each item is normalized separately):\n\n - `'unsigned_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the attributions by the maximum absolute \n attribution value.\n - `'unsigned_max_positive_centered'`: same as above, but scales\n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5. \n - `'magnitude_max'`: takes the absolute value of the \n attributions, then normalizes the attributions to the range \n [0, 1] by dividing by the maximum absolute attribution value.\n - `'magnitude_sum'`: takes the absolute value of the \n attributions, then scales them such that they sum to 1. If \n this option is used, each channel is normalized separately, \n such that each channel sums to 1.\n - `'signed_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the positive values by the maximum \n positive attribution value and the negative values by the \n minimum negative attribution value.\n - `'signed_max_positive_centered'`: same as above, but scales \n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5.\n - `'signed_sum'`: scales the positive attributions such that \n they sum to 1 and the negative attributions such that they\n scale to -1. If this option is used, each channel is \n normalized separately.\n - `'01'`: normalizes the attributions to the range [0, 1] by \n subtracting the minimum attribution value then dividing by the\n maximum attribution value.\n - `'unnormalized'`: leaves the attributions unaffected.\n\n If `None`, defaults to the value supplied to the constructor.\n\n blur:\n Gives the radius of a Gaussian blur to be applied to the \n attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels. If\n `None`, defaults to the value supplied to the constructor.\n\n cmap: matplotlib.colors.Colormap | str, optional\n Colormap or name of a Colormap to use for the visualization. If\n `None`, defaults to the value supplied to the constructor.\n\n Returns:\n A `np.ndarray` array of the numerical representation of the\n attributions as modified for the visualization. This includes \n normalization, blurring, etc.\n \"\"\"\n combine_channels, normalization_type, blur, cmap = self._check_args(\n attributions, combine_channels, normalization_type, blur, cmap\n )\n\n # Combine the channels if specified.\n if combine_channels:\n attributions = attributions.mean(\n axis=get_backend().channel_axis, keepdims=True\n )\n\n # Blur the attributions so the explanation is smoother.\n if blur:\n attributions = self._blur(attributions, blur)\n\n # Normalize the attributions.\n attributions = self._normalize(attributions, normalization_type)\n\n tiled_attributions = self.tiler.tile(attributions)\n\n # Display the figure:\n _fig = plt.figure() if fig is None else fig\n\n plt.axis('off')\n plt.imshow(tiled_attributions, cmap=cmap)\n\n if output_file:\n plt.savefig(output_file, bbox_inches=0)\n\n if imshow:\n plt.show()\n\n elif fig is None:\n plt.close(_fig)\n\n return tiled_attributions if return_tiled else attributions\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.Visualizer.__init__","title":"
__init__(combine_channels=False, normalization_type=None, blur=0.0, cmap=None)","text":"
Configures the default parameters for the __call__ method (these can be overridden by passing in values to __call__).
Parameters:
Name Type Description Default
combine_channels bool If True, the attributions will be averaged across the channel dimension, resulting in a 1-channel attribution map.
False normalization_type str Specifies one of the following configurations for normalizing the attributions (each item is normalized separately):
'unsigned_max': normalizes the attributions to the range [-1, 1] by dividing the attributions by the maximum absolute attribution value.'unsigned_max_positive_centered': same as above, but scales the values to the range [0, 1], with negative scores less than 0.5 and positive scores greater than 0.5. 'magnitude_max': takes the absolute value of the attributions, then normalizes the attributions to the range [0, 1] by dividing by the maximum absolute attribution value.'magnitude_sum': takes the absolute value of the attributions, then scales them such that they sum to 1. If this option is used, each channel is normalized separately, such that each channel sums to 1.'signed_max': normalizes the attributions to the range [-1, 1] by dividing the positive values by the maximum positive attribution value and the negative values by the minimum negative attribution value.'signed_max_positive_centered': same as above, but scales the values to the range [0, 1], with negative scores less than 0.5 and positive scores greater than 0.5.'signed_sum': scales the positive attributions such that they sum to 1 and the negative attributions such that they scale to -1. If this option is used, each channel is normalized separately.'01': normalizes the attributions to the range [0, 1] by subtracting the minimum attribution value then dividing by the maximum attribution value.'unnormalized': leaves the attributions unaffected.
If None, either 'unsigned_max' (for single-channel data) or 'unsigned_max_positive_centered' (for multi-channel data) is used.
None blur float Gives the radius of a Gaussian blur to be applied to the attributions before visualizing. This can be used to help focus on salient regions rather than specific salient pixels.
0.0 cmap Colormap matplotlib.colors.Colormap | str, optional Colormap or name of a Colormap to use for the visualization. If None, the colormap will be chosen based on the normalization type. This argument is only used for single-channel data (including when combine_channels is True).
None Source code in
trulens_explain/trulens/visualizations.py def __init__(\n self,\n combine_channels: bool = False,\n normalization_type: str = None,\n blur: float = 0.,\n cmap: Colormap = None\n):\n \"\"\"\n Configures the default parameters for the `__call__` method (these can \n be overridden by passing in values to `__call__`).\n\n Parameters:\n combine_channels:\n If `True`, the attributions will be averaged across the channel\n dimension, resulting in a 1-channel attribution map.\n\n normalization_type:\n Specifies one of the following configurations for normalizing\n the attributions (each item is normalized separately):\n\n - `'unsigned_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the attributions by the maximum absolute \n attribution value.\n - `'unsigned_max_positive_centered'`: same as above, but scales\n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5. \n - `'magnitude_max'`: takes the absolute value of the \n attributions, then normalizes the attributions to the range \n [0, 1] by dividing by the maximum absolute attribution value.\n - `'magnitude_sum'`: takes the absolute value of the \n attributions, then scales them such that they sum to 1. If \n this option is used, each channel is normalized separately, \n such that each channel sums to 1.\n - `'signed_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the positive values by the maximum \n positive attribution value and the negative values by the \n minimum negative attribution value.\n - `'signed_max_positive_centered'`: same as above, but scales \n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5.\n - `'signed_sum'`: scales the positive attributions such that \n they sum to 1 and the negative attributions such that they\n scale to -1. If this option is used, each channel is \n normalized separately.\n - `'01'`: normalizes the attributions to the range [0, 1] by \n subtracting the minimum attribution value then dividing by the\n maximum attribution value.\n - `'unnormalized'`: leaves the attributions unaffected.\n\n If `None`, either `'unsigned_max'` (for single-channel data) or \n `'unsigned_max_positive_centered'` (for multi-channel data) is\n used.\n\n blur:\n Gives the radius of a Gaussian blur to be applied to the \n attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels.\n\n cmap: matplotlib.colors.Colormap | str, optional\n Colormap or name of a Colormap to use for the visualization. If \n `None`, the colormap will be chosen based on the normalization \n type. This argument is only used for single-channel data\n (including when `combine_channels` is True).\n \"\"\"\n self.default_combine_channels = combine_channels\n self.default_normalization_type = normalization_type\n self.default_blur = blur\n self.default_cmap = cmap if cmap is not None else self._get_hotcold()\n\n # TODO(klas): in the future we can allow configuring of tiling settings\n # by allowing the user to specify the tiler.\n self.tiler = Tiler()\n
"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"conf/","title":"Configuration file for the Sphinx documentation builder.","text":"
Configuration file for the Sphinx documentation builder.
This file only contains a selection of the most common options. For a full list see the documentation: https://www.sphinx-doc.org/en/master/usage/configuration.html
-- Path setup --------------------------------------------------------------
In\u00a0[\u00a0]: Copied!
# If extensions (or modules to document with autodoc) are in another directory,\n# add these directories to sys.path here. If the directory is relative to the\n# documentation root, use os.path.abspath to make it absolute, like shown here.\n#\nimport os\nimport sys\n
# If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # import os import sys In\u00a0[\u00a0]: Copied!
os.environ['TRULENS_BACKEND'] = 'keras'\nsys.path.insert(0, os.path.abspath('.'))\nsys.path.insert(0, os.path.abspath('../'))\n os.environ['TRULENS_BACKEND'] = 'keras' sys.path.insert(0, os.path.abspath('.')) sys.path.insert(0, os.path.abspath('../'))
-- Project information -----------------------------------------------------
In\u00a0[\u00a0]: Copied!
project = 'trulens'\ncopyright = '2023, TruEra'\nauthor = 'TruEra'\n
project = 'trulens' copyright = '2023, TruEra' author = 'TruEra'
-- General configuration ---------------------------------------------------
In\u00a0[\u00a0]: Copied!
# Add any Sphinx extension module names here, as strings. They can be\n# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom\n# ones.\nextensions = [\n 'sphinx.ext.autodoc',\n 'sphinx.ext.napoleon',\n 'recommonmark',\n 'sphinx.ext.mathjax',\n]\n
# Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'recommonmark', 'sphinx.ext.mathjax', ]
napoleon_google_docstring = False napoleon_use_param = False napoleon_use_ivar = True
In\u00a0[\u00a0]: Copied!
def skip(app, what, name, obj, would_skip, options):\n if name == '__init__' or name == '__call__':\n return False\n return would_skip\n
def skip(app, what, name, obj, would_skip, options): if name == '__init__' or name == '__call__': return False return would_skip In\u00a0[\u00a0]: Copied!
def setup(app):\n app.connect('autodoc-skip-member', skip)\n def setup(app): app.connect('autodoc-skip-member', skip) In\u00a0[\u00a0]: Copied!
# Add any paths that contain templates here, relative to this directory.\ntemplates_path = ['_templates']\n
# Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] In\u00a0[\u00a0]: Copied!
# List of patterns, relative to source directory, that match files and\n# directories to ignore when looking for source files.\n# This pattern also affects html_static_path and html_extra_path.\nexclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']\n
# List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
-- Options for HTML output -------------------------------------------------
In\u00a0[\u00a0]: Copied!
# The theme to use for HTML and HTML Help pages. See the documentation for\n# a list of builtin themes.\n#\nhtml_theme = 'sphinx_rtd_theme'\n
# The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # html_theme = 'sphinx_rtd_theme' In\u00a0[\u00a0]: Copied!
# Add any paths that contain custom static files (such as style sheets) here,\n# relative to this directory. They are copied after the builtin static files,\n# so a file named \"default.css\" will overwrite the builtin \"default.css\".\nhtml_static_path = ['_static']\n
# Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named \"default.css\" will overwrite the builtin \"default.css\". html_static_path = ['_static'] In\u00a0[\u00a0]: Copied!
from recommonmark.parser import CommonMarkParser\n
from recommonmark.parser import CommonMarkParser In\u00a0[\u00a0]: Copied!
source_parsers = {'.md': CommonMarkParser}\n source_parsers = {'.md': CommonMarkParser} In\u00a0[\u00a0]: Copied!
source_suffix = ['.rst', '.md']\n
source_suffix = ['.rst', '.md']"},{"location":"welcome/","title":"Welcome to TruLens!","text":""},{"location":"welcome/#welcome-to-trulens","title":"\ud83e\udd91 Welcome to TruLens!","text":"
TruLens provides a set of tools for developing and monitoring neural nets, including large language models. This includes both tools for evaluation of LLMs and LLM-based applications with TruLens-Eval and deep learning explainability with TruLens-Explain. TruLens-Eval and TruLens-Explain are housed in separate packages and can be used independently.
The best way to support TruLens is to give us a \u2b50 and join our slack community!
"},{"location":"welcome/#trulens-eval","title":"TruLens-Eval","text":"
TruLens-Eval contains instrumentation and evaluation tools for large language model (LLM) based applications. It supports the iterative development and monitoring of a wide range of LLM applications by wrapping your application to log key metadata across the entire chain (or off chain if your project does not use chains) on your local machine. Importantly, it also gives you the tools you need to evaluate the quality of your LLM-based applications.
TruLens-Eval has two key value propositions:
- Evaluation:
- TruLens supports the evaluation of inputs, outputs and internals of your LLM application using any model (including LLMs).
- A number of feedback functions for evaluation are implemented out-of-the-box such as groundedness, relevance and toxicity. The framework is also easily extensible for custom evaluation requirements.
- Tracking:
- TruLens contains instrumentation for any LLM application including question answering, retrieval-augmented generation, agent-based applications and more. This instrumentation allows for the tracking of a wide variety of usage metrics and metadata. Read more in the instrumentation overview.
- TruLens' instrumentation can be applied to any LLM application without being tied down to a given framework. Additionally, deep integrations with LangChain and Llama-Index allow the capture of internal metadata and text.
- Anything that is tracked by the instrumentation can be evaluated!
The process for building your evaluated and tracked LLM application with TruLens is shown below \ud83d\udc47
"},{"location":"welcome/#installation-and-setup","title":"Installation and setup","text":"
Install trulens-eval from PyPI.
pip install trulens-eval\n
"},{"location":"welcome/#quick-usage","title":"Quick Usage","text":"
TruLens supports the evaluation of tracking for any LLM app framework. Choose a framework below to get started:
Langchain
langchain_quickstart.ipynb.
Llama-Index
llama_index_quickstart.ipynb.
Custom Text to Text Apps
text2text_quickstart.ipynb.
"},{"location":"welcome/#trulens-explain","title":"TruLens-Explain","text":"
TruLens-Explain is a cross-framework library for deep learning explainability. It provides a uniform abstraction over a number of different frameworks. It provides a uniform abstraction layer over TensorFlow, Pytorch, and Keras and allows input and internal explanations.
"},{"location":"welcome/#installation-and-setup_1","title":"Installation and Setup","text":"
These installation instructions assume that you have conda installed and added to your path.
-
Create a virtual environment (or modify an existing one).
conda create -n \"<my_name>\" python=3 # Skip if using existing environment.\nconda activate <my_name>\n
-
Install dependencies.
conda install tensorflow-gpu=1 # Or whatever backend you're using.\nconda install keras # Or whatever backend you're using.\nconda install matplotlib # For visualizations.\n
-
[Pip installation] Install the trulens pip package from PyPI.
pip install trulens\n
"},{"location":"welcome/#quick-usage_1","title":"Quick Usage","text":"
To quickly play around with the TruLens library, check out the following Colab notebooks:
- PyTorch:
- TensorFlow 2 / Keras:
For more information, see TruLens-Explain Documentation.
"},{"location":"welcome2/","title":"Welcome2","text":""},{"location":"welcome2/#welcome-to-trulens","title":"\ud83e\udd91 Welcome to TruLens!","text":"
TruLens provides a set of tools for developing and monitoring neural nets, including large language models. This includes both tools for evaluation of LLMs and LLM-based applications with TruLens-Eval and deep learning explainability with TruLens-Explain. TruLens-Eval and TruLens-Explain are housed in separate packages and can be used independently.
The best way to support TruLens is to give us a \u2b50 and join our slack community!
"},{"location":"welcome2/#trulens-eval","title":"TruLens-Eval","text":"
TruLens-Eval contains instrumentation and evaluation tools for large language model (LLM) based applications. It supports the iterative development and monitoring of a wide range of LLM applications by wrapping your application to log key metadata across the entire chain (or off chain if your project does not use chains) on your local machine. Importantly, it also gives you the tools you need to evaluate the quality of your LLM-based applications.
TruLens-Eval has two key value propositions:
- Evaluation:
- TruLens supports the evaluation of inputs, outputs and internals of your LLM application using any model (including LLMs).
- A number of feedback functions for evaluation are implemented out-of-the-box such as groundedness, relevance and toxicity. The framework is also easily extensible for custom evaluation requirements.
- Tracking:
- TruLens contains instrumentation for any LLM application including question answering, retrieval-augmented generation, agent-based applications and more. This instrumentation allows for the tracking of a wide variety of usage metrics and metadata. Read more in the instrumentation overview.
- TruLens' instrumentation can be applied to any LLM application without being tied down to a given framework. Additionally, deep integrations with LangChain and Llama-Index allow the capture of internal metadata and text.
- Anything that is tracked by the instrumentation can be evaluated!
The process for building your evaluated and tracked LLM application with TruLens is shown below \ud83d\udc47
"},{"location":"welcome2/#installation-and-setup","title":"Installation and setup","text":"
Install trulens-eval from PyPI.
pip install trulens-eval\n
"},{"location":"welcome2/#quick-usage","title":"Quick Usage","text":"
TruLens supports the evaluation of tracking for any LLM app framework. Choose a framework below to get started:
Langchain
langchain_quickstart.ipynb.
Llama-Index
llama_index_quickstart.ipynb.
Custom Text to Text Apps
text2text_quickstart.ipynb.
"},{"location":"welcome2/#trulens-explain","title":"TruLens-Explain","text":"
TruLens-Explain is a cross-framework library for deep learning explainability. It provides a uniform abstraction over a number of different frameworks. It provides a uniform abstraction layer over TensorFlow, Pytorch, and Keras and allows input and internal explanations.
"},{"location":"welcome2/#installation-and-setup_1","title":"Installation and Setup","text":"
These installation instructions assume that you have conda installed and added to your path.
-
Create a virtual environment (or modify an existing one).
conda create -n \"<my_name>\" python=3 # Skip if using existing environment.\nconda activate <my_name>\n
-
Install dependencies.
conda install tensorflow-gpu=1 # Or whatever backend you're using.\nconda install keras # Or whatever backend you're using.\nconda install matplotlib # For visualizations.\n
-
[Pip installation] Install the trulens pip package from PyPI.
pip install trulens\n
"},{"location":"welcome2/#quick-usage_1","title":"Quick Usage","text":"
To quickly play around with the TruLens library, check out the following Colab notebooks:
- PyTorch:
- TensorFlow 2 / Keras:
For more information, see TruLens-Explain Documentation.
"},{"location":"trulens_eval/CONTRIBUTING/","title":"Contributing to TruLens","text":"
Interested in contributing to TruLens? Here's how to get started!
"},{"location":"trulens_eval/CONTRIBUTING/#what-can-you-work-on","title":"What can you work on?","text":"
- \ud83d\udcaa Add new feedback functions
- \ud83e\udd1d Add new feedback function providers.
- \ud83d\udc1b Fix bugs
- \ud83c\udf89 Add usage examples
- \ud83e\uddea Add experimental features
- \ud83d\udcc4 Improve code quality & documentation
Also, join the AI Quality Slack community for ideas and discussions.
"},{"location":"trulens_eval/CONTRIBUTING/#add-new-feedback-functions","title":"\ud83d\udcaa Add new feedback functions","text":"
Feedback functions are the backbone of TruLens, and evaluating unique LLM apps may require new evaluations. We'd love your contribution to extend the feedback functions library so others can benefit!
- To add a feedback function for an existing model provider, you can add it to an existing provider module. You can read more about the structure of a feedback function in this guide.
- New methods can either take a single text (str) as a parameter or two different texts (str), such as prompt and retrieved context. It should return a float, or a dict of multiple floats. Each output value should be a float on the scale of 0 (worst) to 1 (best).
- Make sure to add its definition to this list.
"},{"location":"trulens_eval/CONTRIBUTING/#add-new-feedback-function-providers","title":"\ud83e\udd1d Add new feedback function providers.","text":"
Feedback functions often rely on a model provider, such as OpenAI or HuggingFace. If you need a new model provider to utilize feedback functions for your use case, we'd love if you added a new provider class, e.g. AzureOpenAI.
You can do so by creating a new provider module in this folder.
Alternatively, we also appreciate if you open a GitHub Issue if there's a model provider you need!
"},{"location":"trulens_eval/CONTRIBUTING/#fix-bugs","title":"\ud83d\udc1b Fix Bugs","text":"
Most bugs are reported and tracked in the Github Issues Page. We try our best in triaging and tagging these issues:
Issues tagged as bug are confirmed bugs. New contributors may want to start with issues tagged with good first issue. Please feel free to open an issue and/or assign an issue to yourself.
"},{"location":"trulens_eval/CONTRIBUTING/#add-usage-examples","title":"\ud83c\udf89 Add Usage Examples","text":"
If you have applied TruLens to track and evalaute a unique use-case, we would love your contribution in the form of an example notebook: e.g. Evaluating Pinecone Configuration Choices on Downstream App Performance
All example notebooks are expected to:
- Start with a title and description of the example
- Include a commented out list of dependencies and their versions, e.g.
# ! pip install trulens==0.10.0 langchain==0.0.268 - Include a linked button to a Google colab version of the notebook
- Add any additional requirements
"},{"location":"trulens_eval/CONTRIBUTING/#add-experimental-features","title":"\ud83e\uddea Add Experimental Features","text":"
If you have a crazy idea, make a PR for it! Whether if it's the latest research, or what you thought of in the shower, we'd love to see creative ways to improve TruLens.
"},{"location":"trulens_eval/CONTRIBUTING/#improve-code-quality-documentation","title":"\ud83d\udcc4 Improve Code Quality & Documentation","text":"
We would love your help in making the project cleaner, more robust, and more understandable. If you find something confusing, it most likely is for other people as well. Help us be better!
"},{"location":"trulens_eval/answer_relevance_smoke_tests/","title":"Answer Relevance","text":"In\u00a0[1]: Copied!
# Import relevance feedback function\nfrom trulens_eval.feedback import GroundTruthAgreement, OpenAI, LiteLLM\nfrom trulens_eval import TruBasicApp, Feedback, Tru, Select\nfrom test_cases import answer_relevance_golden_set\n\nTru().reset_database()\n
# Import relevance feedback function from trulens_eval.feedback import GroundTruthAgreement, OpenAI, LiteLLM from trulens_eval import TruBasicApp, Feedback, Tru, Select from test_cases import answer_relevance_golden_set Tru().reset_database()
\ud83e\udd91 Tru initialized with db url sqlite:///default.sqlite .\n\ud83d\uded1 Secret keys may be written to the database. See the `database_redact_keys` option of `Tru` to prevent this.\nDeleted 9 rows.\n
In\u00a0[2]: Copied!
import os\nos.environ[\"OPENAI_API_KEY\"] = \"...\"\nos.environ[\"COHERE_API_KEY\"] = \"...\"\nos.environ[\"HUGGINGFACE_API_KEY\"] = \"...\"\nos.environ[\"ANTHROPIC_API_KEY\"] = \"...\"\nos.environ[\"TOGETHERAI_API_KEY\"] = \"...\"\n
import os os.environ[\"OPENAI_API_KEY\"] = \"...\" os.environ[\"COHERE_API_KEY\"] = \"...\" os.environ[\"HUGGINGFACE_API_KEY\"] = \"...\" os.environ[\"ANTHROPIC_API_KEY\"] = \"...\" os.environ[\"TOGETHERAI_API_KEY\"] = \"...\" In\u00a0[3]: Copied!
# GPT 3.5\nturbo = OpenAI(model_engine=\"gpt-3.5-turbo\")\n\ndef wrapped_relevance_turbo(input, output):\n return turbo.relevance(input, output)\n\n# GPT 4\ngpt4 = OpenAI(model_engine=\"gpt-4\")\n\ndef wrapped_relevance_gpt4(input, output):\n return gpt4.relevance(input, output)\n\n# Cohere\ncommand_nightly = LiteLLM(model_engine=\"cohere/command-nightly\")\ndef wrapped_relevance_command_nightly(input, output):\n return command_nightly.relevance(input, output)\n\n# Anthropic\nclaude_1 = LiteLLM(model_engine=\"claude-instant-1\")\ndef wrapped_relevance_claude1(input, output):\n return claude_1.relevance(input, output)\n\nclaude_2 = LiteLLM(model_engine=\"claude-2\")\ndef wrapped_relevance_claude2(input, output):\n return claude_2.relevance(input, output)\n\n# Meta\nllama_2_13b = LiteLLM(model_engine=\"together_ai/togethercomputer/Llama-2-7B-32K-Instruct\")\ndef wrapped_relevance_llama2(input, output):\n return llama_2_13b.relevance(input, output)\n
# GPT 3.5 turbo = OpenAI(model_engine=\"gpt-3.5-turbo\") def wrapped_relevance_turbo(input, output): return turbo.relevance(input, output) # GPT 4 gpt4 = OpenAI(model_engine=\"gpt-4\") def wrapped_relevance_gpt4(input, output): return gpt4.relevance(input, output) # Cohere command_nightly = LiteLLM(model_engine=\"cohere/command-nightly\") def wrapped_relevance_command_nightly(input, output): return command_nightly.relevance(input, output) # Anthropic claude_1 = LiteLLM(model_engine=\"claude-instant-1\") def wrapped_relevance_claude1(input, output): return claude_1.relevance(input, output) claude_2 = LiteLLM(model_engine=\"claude-2\") def wrapped_relevance_claude2(input, output): return claude_2.relevance(input, output) # Meta llama_2_13b = LiteLLM(model_engine=\"together_ai/togethercomputer/Llama-2-7B-32K-Instruct\") def wrapped_relevance_llama2(input, output): return llama_2_13b.relevance(input, output)
Here we'll set up our golden set as a set of prompts, responses and expected scores stored in test_cases.py. Then, our numeric_difference method will look up the expected score for each prompt/response pair by exact match. After looking up the expected score, we will then take the L1 difference between the actual score and expected score.
In\u00a0[4]: Copied!
# Create a Feedback object using the numeric_difference method of the ground_truth object\nground_truth = GroundTruthAgreement(answer_relevance_golden_set)\n# Call the numeric_difference method with app and record and aggregate to get the mean absolute error\nf_mae = Feedback(ground_truth.mae, name = \"Mean Absolute Error\").on(Select.Record.calls[0].args.args[0]).on(Select.Record.calls[0].args.args[1]).on_output()\n
# Create a Feedback object using the numeric_difference method of the ground_truth object ground_truth = GroundTruthAgreement(answer_relevance_golden_set) # Call the numeric_difference method with app and record and aggregate to get the mean absolute error f_mae = Feedback(ground_truth.mae, name = \"Mean Absolute Error\").on(Select.Record.calls[0].args.args[0]).on(Select.Record.calls[0].args.args[1]).on_output()
\u2705 In Mean Absolute Error, input prompt will be set to __record__.calls[0].args.args[0] .\n\u2705 In Mean Absolute Error, input response will be set to __record__.calls[0].args.args[1] .\n\u2705 In Mean Absolute Error, input score will be set to __record__.main_output or `Select.RecordOutput` .\n
In\u00a0[5]: Copied!
tru_wrapped_relevance_turbo = TruBasicApp(wrapped_relevance_turbo, app_id = \"answer relevance gpt-3.5-turbo\", feedbacks=[f_mae])\n\ntru_wrapped_relevance_gpt4 = TruBasicApp(wrapped_relevance_gpt4, app_id = \"answer relevance gpt-4\", feedbacks=[f_mae])\n\ntru_wrapped_relevance_commandnightly = TruBasicApp(wrapped_relevance_command_nightly, app_id = \"answer relevance Command-Nightly\", feedbacks=[f_mae])\n\ntru_wrapped_relevance_claude1 = TruBasicApp(wrapped_relevance_claude1, app_id = \"answer relevance Claude 1\", feedbacks=[f_mae])\n\ntru_wrapped_relevance_claude2 = TruBasicApp(wrapped_relevance_claude2, app_id = \"answer relevance Claude 2\", feedbacks=[f_mae])\n\ntru_wrapped_relevance_llama2 = TruBasicApp(wrapped_relevance_llama2, app_id = \"answer relevance Llama-2-13b\", feedbacks=[f_mae])\n
tru_wrapped_relevance_turbo = TruBasicApp(wrapped_relevance_turbo, app_id = \"answer relevance gpt-3.5-turbo\", feedbacks=[f_mae]) tru_wrapped_relevance_gpt4 = TruBasicApp(wrapped_relevance_gpt4, app_id = \"answer relevance gpt-4\", feedbacks=[f_mae]) tru_wrapped_relevance_commandnightly = TruBasicApp(wrapped_relevance_command_nightly, app_id = \"answer relevance Command-Nightly\", feedbacks=[f_mae]) tru_wrapped_relevance_claude1 = TruBasicApp(wrapped_relevance_claude1, app_id = \"answer relevance Claude 1\", feedbacks=[f_mae]) tru_wrapped_relevance_claude2 = TruBasicApp(wrapped_relevance_claude2, app_id = \"answer relevance Claude 2\", feedbacks=[f_mae]) tru_wrapped_relevance_llama2 = TruBasicApp(wrapped_relevance_llama2, app_id = \"answer relevance Llama-2-13b\", feedbacks=[f_mae])
\u2705 added app answer relevance gpt-3.5-turbo\n\u2705 added feedback definition feedback_definition_hash_d2c7c6ef797c4fdbdcb802c0c74d451a\n\u2705 added app answer relevance with cot reasoning gpt-3.5-turbo\n\u2705 added feedback definition feedback_definition_hash_d2c7c6ef797c4fdbdcb802c0c74d451a\n\u2705 added app answer relevance gpt-4\n\u2705 added feedback definition feedback_definition_hash_d2c7c6ef797c4fdbdcb802c0c74d451a\n\u2705 added app answer relevance with cot reasoning gpt-4\n\u2705 added feedback definition feedback_definition_hash_d2c7c6ef797c4fdbdcb802c0c74d451a\n\u2705 added app answer relevance Command-Nightly\n\u2705 added feedback definition feedback_definition_hash_d2c7c6ef797c4fdbdcb802c0c74d451a\n\u2705 added app answer relevance Claude 1\n\u2705 added feedback definition feedback_definition_hash_d2c7c6ef797c4fdbdcb802c0c74d451a\n\u2705 added app answer relevance Claude 2\n\u2705 added feedback definition feedback_definition_hash_d2c7c6ef797c4fdbdcb802c0c74d451a\n\u2705 added app answer relevance Llama-2-13b\n\u2705 added feedback definition feedback_definition_hash_d2c7c6ef797c4fdbdcb802c0c74d451a\n
In\u00a0[\u00a0]: Copied!
for i in range(len(answer_relevance_golden_set)):\n prompt = answer_relevance_golden_set[i][\"query\"]\n response = answer_relevance_golden_set[i][\"response\"]\n \n with tru_wrapped_relevance_turbo as recording:\n tru_wrapped_relevance_turbo.app(prompt, response)\n \n with tru_wrapped_relevance_gpt4 as recording:\n tru_wrapped_relevance_gpt4.app(prompt, response)\n \n with tru_wrapped_relevance_commandnightly as recording:\n tru_wrapped_relevance_commandnightly.app(prompt, response)\n \n with tru_wrapped_relevance_claude1 as recording:\n tru_wrapped_relevance_claude1.app(prompt, response)\n\n with tru_wrapped_relevance_claude2 as recording:\n tru_wrapped_relevance_claude2.app(prompt, response)\n\n with tru_wrapped_relevance_llama2 as recording:\n tru_wrapped_relevance_llama2.app(prompt, response)\n
for i in range(len(answer_relevance_golden_set)): prompt = answer_relevance_golden_set[i][\"query\"] response = answer_relevance_golden_set[i][\"response\"] with tru_wrapped_relevance_turbo as recording: tru_wrapped_relevance_turbo.app(prompt, response) with tru_wrapped_relevance_gpt4 as recording: tru_wrapped_relevance_gpt4.app(prompt, response) with tru_wrapped_relevance_commandnightly as recording: tru_wrapped_relevance_commandnightly.app(prompt, response) with tru_wrapped_relevance_claude1 as recording: tru_wrapped_relevance_claude1.app(prompt, response) with tru_wrapped_relevance_claude2 as recording: tru_wrapped_relevance_claude2.app(prompt, response) with tru_wrapped_relevance_llama2 as recording: tru_wrapped_relevance_llama2.app(prompt, response) In\u00a0[12]: Copied!
Tru().get_leaderboard(app_ids=[]).sort_values(by='Mean Absolute Error')\n
Tru().get_leaderboard(app_ids=[]).sort_values(by='Mean Absolute Error') Out[12]: Mean Absolute Error latency total_cost app_id answer relevance gpt-3.5-turbo 0.172727 0.090909 0.000739 answer relevance gpt-4 0.245455 0.090909 0.014804 answer relevance Claude 1 0.250000 0.100000 0.000000 answer relevance Claude 2 0.300000 0.100000 0.000000 answer relevance Command-Nightly 0.300000 0.100000 0.000000 answer relevance Llama-2-13b 0.590000 0.100000 0.000000"},{"location":"trulens_eval/answer_relevance_smoke_tests/#answer-relevance-feedback-evaluation","title":"Answer Relevance Feedback Evaluation\u00b6","text":"
In many ways, feedbacks can be thought of as LLM apps themselves. Given text, they return some result. Thinking in this way, we can use TruLens to evaluate and track our feedback quality. We can even do this for different models (e.g. gpt-3.5 and gpt-4) or prompting schemes (such as chain-of-thought reasoning).
This notebook follows an evaluation of a set of test cases. You are encouraged to run this on your own and even expand the test cases to evaluate performance on test cases applicable to your scenario or domain.
"},{"location":"trulens_eval/basic_instrumentation/","title":"Overview","text":"In\u00a0[\u00a0]: Copied!
def custom_application(prompt: str) -> str:\n return \"a response\"\n
def custom_application(prompt: str) -> str: return \"a response\"
After creating the application, TruBasicApp allows you to instrument it in one line of code:
In\u00a0[\u00a0]: Copied!
from trulens_eval import TruBasicApp\nbasic_app_recorder = TruBasicApp(custom_application, app_id=\"Custom Application v1\")\n
from trulens_eval import TruBasicApp basic_app_recorder = TruBasicApp(custom_application, app_id=\"Custom Application v1\")
Then, you can operate the application like normal:
In\u00a0[\u00a0]: Copied!
with basic_app_recorder as recording:\n basic_app_recorder.app(\"What is the phone number for HR?\")\n
with basic_app_recorder as recording: basic_app_recorder.app(\"What is the phone number for HR?\")
Read more about TruBasicApp in the API reference or check out the text2text quickstart.
If instead, you're looking to use TruLens with a more complex custom application, you can use TruCustom.
For more information, plese read more about TruCustom in the API Reference
"},{"location":"trulens_eval/basic_instrumentation/#overview","title":"Overview\u00b6","text":"
TruLens provides a number of different instrumentation frameworks to allow you to inspect and evaluate the internals of your application and its associated records. In any framework you can track a wide variety of usage metrics and metadata, detailed below, along with the inputs and outputs of the application. For frameworks with deep integrations, TruLens can expose additional internals of the application for tracking.
"},{"location":"trulens_eval/basic_instrumentation/#what-can-you-track","title":"What can you track?\u00b6","text":""},{"location":"trulens_eval/basic_instrumentation/#usage-metrics","title":"Usage Metrics\u00b6","text":"
- Number of requests (n_requests)
- Number of successful ones (n_successful_requests)
- Number of class scores retrieved (n_classes)
- Total tokens processed (n_tokens)
- In streaming mode, number of chunks produced (n_stream_chunks)
- Number of prompt tokens supplied (n_prompt_tokens)
- Number of completion tokens generated (n_completion_tokens)
- Cost in USD (cost)
"},{"location":"trulens_eval/basic_instrumentation/#app-metadata","title":"App Metadata\u00b6","text":"
- App ID (app_id) - user supplied string or automatically generated hash
- Tags (tags) - user supplied string
- Model metadata - user supplied json
"},{"location":"trulens_eval/basic_instrumentation/#record-metadata","title":"Record Metadata\u00b6","text":"
- Record ID (record_id) - automatically generated, track individual application calls
- Timestamp (ts) - automatcially tracked, the timestamp of the application call
- Latency (latency) - the difference between the application call start and end time.
"},{"location":"trulens_eval/basic_instrumentation/#tracking-custom-applications","title":"Tracking custom applications\u00b6","text":"
Outside of integrations, TruLens supports the instrumentation of any text-to-text application, including custom ones.
The way to track this type of application is through TruBasicApp.
Suppose you have a generic text-to-text application as follows:
"},{"location":"trulens_eval/context_relevance_smoke_tests/","title":"Context Relevance","text":"In\u00a0[1]: Copied!
# Import relevance feedback function\nfrom trulens_eval.feedback import GroundTruthAgreement, OpenAI, LiteLLM\nfrom trulens_eval import TruBasicApp, Feedback, Tru, Select\nfrom test_cases import context_relevance_golden_set\n\nimport openai\n\nTru().reset_database()\n
# Import relevance feedback function from trulens_eval.feedback import GroundTruthAgreement, OpenAI, LiteLLM from trulens_eval import TruBasicApp, Feedback, Tru, Select from test_cases import context_relevance_golden_set import openai Tru().reset_database()
\ud83e\udd91 Tru initialized with db url sqlite:///default.sqlite .\n\ud83d\uded1 Secret keys may be written to the database. See the `database_redact_keys` option of `Tru` to prevent this.\nDeleted 17 rows.\n
In\u00a0[2]: Copied!
import os\nos.environ[\"OPENAI_API_KEY\"] = \"...\"\nos.environ[\"COHERE_API_KEY\"] = \"...\"\nos.environ[\"HUGGINGFACE_API_KEY\"] = \"...\"\nos.environ[\"ANTHROPIC_API_KEY\"] = \"...\"\nos.environ[\"TOGETHERAI_API_KEY\"] = \"...\"\n
import os os.environ[\"OPENAI_API_KEY\"] = \"...\" os.environ[\"COHERE_API_KEY\"] = \"...\" os.environ[\"HUGGINGFACE_API_KEY\"] = \"...\" os.environ[\"ANTHROPIC_API_KEY\"] = \"...\" os.environ[\"TOGETHERAI_API_KEY\"] = \"...\" In\u00a0[3]: Copied!
# GPT 3.5\nturbo = OpenAI(model_engine=\"gpt-3.5-turbo\")\n\ndef wrapped_relevance_turbo(input, output):\n return turbo.qs_relevance(input, output)\n\n# GPT 4\ngpt4 = OpenAI(model_engine=\"gpt-4\")\n\ndef wrapped_relevance_gpt4(input, output):\n return gpt4.qs_relevance(input, output)\n\n# Cohere\ncommand_nightly = LiteLLM(model_engine=\"command-nightly\")\ndef wrapped_relevance_command_nightly(input, output):\n return command_nightly.qs_relevance(input, output)\n\n# Anthropic\nclaude_1 = LiteLLM(model_engine=\"claude-instant-1\")\ndef wrapped_relevance_claude1(input, output):\n return claude_1.qs_relevance(input, output)\n\nclaude_2 = LiteLLM(model_engine=\"claude-2\")\ndef wrapped_relevance_claude2(input, output):\n return claude_2.qs_relevance(input, output)\n\n# Meta\nllama_2_13b = LiteLLM(model_engine=\"together_ai/togethercomputer/Llama-2-7B-32K-Instruct\")\ndef wrapped_relevance_llama2(input, output):\n return llama_2_13b.qs_relevance(input, output)\n
# GPT 3.5 turbo = OpenAI(model_engine=\"gpt-3.5-turbo\") def wrapped_relevance_turbo(input, output): return turbo.qs_relevance(input, output) # GPT 4 gpt4 = OpenAI(model_engine=\"gpt-4\") def wrapped_relevance_gpt4(input, output): return gpt4.qs_relevance(input, output) # Cohere command_nightly = LiteLLM(model_engine=\"command-nightly\") def wrapped_relevance_command_nightly(input, output): return command_nightly.qs_relevance(input, output) # Anthropic claude_1 = LiteLLM(model_engine=\"claude-instant-1\") def wrapped_relevance_claude1(input, output): return claude_1.qs_relevance(input, output) claude_2 = LiteLLM(model_engine=\"claude-2\") def wrapped_relevance_claude2(input, output): return claude_2.qs_relevance(input, output) # Meta llama_2_13b = LiteLLM(model_engine=\"together_ai/togethercomputer/Llama-2-7B-32K-Instruct\") def wrapped_relevance_llama2(input, output): return llama_2_13b.qs_relevance(input, output)
Here we'll set up our golden set as a set of prompts, responses and expected scores stored in test_cases.py. Then, our numeric_difference method will look up the expected score for each prompt/response pair by exact match. After looking up the expected score, we will then take the L1 difference between the actual score and expected score.
In\u00a0[4]: Copied!
# Create a Feedback object using the numeric_difference method of the ground_truth object\nground_truth = GroundTruthAgreement(context_relevance_golden_set)\n# Call the numeric_difference method with app and record and aggregate to get the mean absolute error\nf_mae = Feedback(ground_truth.mae, name = \"Mean Absolute Error\").on(Select.Record.calls[0].args.args[0]).on(Select.Record.calls[0].args.args[1]).on_output()\n
# Create a Feedback object using the numeric_difference method of the ground_truth object ground_truth = GroundTruthAgreement(context_relevance_golden_set) # Call the numeric_difference method with app and record and aggregate to get the mean absolute error f_mae = Feedback(ground_truth.mae, name = \"Mean Absolute Error\").on(Select.Record.calls[0].args.args[0]).on(Select.Record.calls[0].args.args[1]).on_output()
\u2705 In Mean Absolute Error, input prompt will be set to __record__.calls[0].args.args[0] .\n\u2705 In Mean Absolute Error, input response will be set to __record__.calls[0].args.args[1] .\n\u2705 In Mean Absolute Error, input score will be set to __record__.main_output or `Select.RecordOutput` .\n
In\u00a0[5]: Copied!
tru_wrapped_relevance_turbo = TruBasicApp(wrapped_relevance_turbo, app_id = \"context relevance gpt-3.5-turbo\", feedbacks=[f_mae])\n\ntru_wrapped_relevance_gpt4 = TruBasicApp(wrapped_relevance_gpt4, app_id = \"context relevance gpt-4\", feedbacks=[f_mae])\n\ntru_wrapped_relevance_commandnightly = TruBasicApp(wrapped_relevance_command_nightly, app_id = \"context relevance Command-Nightly\", feedbacks=[f_mae])\n\ntru_wrapped_relevance_claude1 = TruBasicApp(wrapped_relevance_claude1, app_id = \"context relevance Claude 1\", feedbacks=[f_mae])\n\ntru_wrapped_relevance_claude2 = TruBasicApp(wrapped_relevance_claude2, app_id = \"context relevance Claude 2\", feedbacks=[f_mae])\n\ntru_wrapped_relevance_llama2 = TruBasicApp(wrapped_relevance_llama2, app_id = \"context relevance Llama-2-13b\", feedbacks=[f_mae])\n
tru_wrapped_relevance_turbo = TruBasicApp(wrapped_relevance_turbo, app_id = \"context relevance gpt-3.5-turbo\", feedbacks=[f_mae]) tru_wrapped_relevance_gpt4 = TruBasicApp(wrapped_relevance_gpt4, app_id = \"context relevance gpt-4\", feedbacks=[f_mae]) tru_wrapped_relevance_commandnightly = TruBasicApp(wrapped_relevance_command_nightly, app_id = \"context relevance Command-Nightly\", feedbacks=[f_mae]) tru_wrapped_relevance_claude1 = TruBasicApp(wrapped_relevance_claude1, app_id = \"context relevance Claude 1\", feedbacks=[f_mae]) tru_wrapped_relevance_claude2 = TruBasicApp(wrapped_relevance_claude2, app_id = \"context relevance Claude 2\", feedbacks=[f_mae]) tru_wrapped_relevance_llama2 = TruBasicApp(wrapped_relevance_llama2, app_id = \"context relevance Llama-2-13b\", feedbacks=[f_mae])
\u2705 added app context relevance gpt-3.5-turbo\n\u2705 added feedback definition feedback_definition_hash_ac1d5b3a2009be5efdb59a1f22e23053\n\u2705 added app context relevance gpt-4\n\u2705 added feedback definition feedback_definition_hash_ac1d5b3a2009be5efdb59a1f22e23053\n\u2705 added app context relevance Command-Nightly\n\u2705 added feedback definition feedback_definition_hash_ac1d5b3a2009be5efdb59a1f22e23053\n\u2705 added app context relevance Claude 1\n\u2705 added feedback definition feedback_definition_hash_ac1d5b3a2009be5efdb59a1f22e23053\n\u2705 added app context relevance Claude 2\n\u2705 added feedback definition feedback_definition_hash_ac1d5b3a2009be5efdb59a1f22e23053\n\u2705 added app context relevance Llama-2-13b\n\u2705 added feedback definition feedback_definition_hash_ac1d5b3a2009be5efdb59a1f22e23053\n
In\u00a0[\u00a0]: Copied!
for i in range(len(context_relevance_golden_set)):\n prompt = context_relevance_golden_set[i][\"query\"]\n response = context_relevance_golden_set[i][\"response\"]\n with tru_wrapped_relevance_turbo as recording:\n tru_wrapped_relevance_turbo.app(prompt, response)\n \n with tru_wrapped_relevance_gpt4 as recording:\n tru_wrapped_relevance_gpt4.app(prompt, response)\n \n with tru_wrapped_relevance_commandnightly as recording:\n tru_wrapped_relevance_commandnightly.app(prompt, response)\n \n with tru_wrapped_relevance_claude1 as recording:\n tru_wrapped_relevance_claude1.app(prompt, response)\n\n with tru_wrapped_relevance_claude2 as recording:\n tru_wrapped_relevance_claude2.app(prompt, response)\n\n with tru_wrapped_relevance_llama2 as recording:\n tru_wrapped_relevance_llama2.app(prompt, response)\n
for i in range(len(context_relevance_golden_set)): prompt = context_relevance_golden_set[i][\"query\"] response = context_relevance_golden_set[i][\"response\"] with tru_wrapped_relevance_turbo as recording: tru_wrapped_relevance_turbo.app(prompt, response) with tru_wrapped_relevance_gpt4 as recording: tru_wrapped_relevance_gpt4.app(prompt, response) with tru_wrapped_relevance_commandnightly as recording: tru_wrapped_relevance_commandnightly.app(prompt, response) with tru_wrapped_relevance_claude1 as recording: tru_wrapped_relevance_claude1.app(prompt, response) with tru_wrapped_relevance_claude2 as recording: tru_wrapped_relevance_claude2.app(prompt, response) with tru_wrapped_relevance_llama2 as recording: tru_wrapped_relevance_llama2.app(prompt, response) In\u00a0[7]: Copied!
Tru().get_leaderboard(app_ids=[]).sort_values(by=\"Mean Absolute Error\")\n
Tru().get_leaderboard(app_ids=[]).sort_values(by=\"Mean Absolute Error\")
\u2705 feedback result Mean Absolute Error DONE feedback_result_hash_086ffca9b39fe36e86797171e56e3f50\n
Out[7]: Mean Absolute Error latency total_cost app_id context relevance Claude 1 0.186667 0.066667 0.000000 context relevance gpt-3.5-turbo 0.206667 0.066667 0.000762 context relevance gpt-4 0.253333 0.066667 0.015268 context relevance Command-Nightly 0.313333 0.066667 0.000000 context relevance Claude 2 0.366667 0.066667 0.000000 context relevance Llama-2-13b 0.586667 0.066667 0.000000"},{"location":"trulens_eval/context_relevance_smoke_tests/#context-relevance-evaluations","title":"Context Relevance Evaluations\u00b6","text":"
In many ways, feedbacks can be thought of as LLM apps themselves. Given text, they return some result. Thinking in this way, we can use TruLens to evaluate and track our feedback quality. We can even do this for different models (e.g. gpt-3.5 and gpt-4) or prompting schemes (such as chain-of-thought reasoning).
This notebook follows an evaluation of a set of test cases. You are encouraged to run this on your own and even expand the test cases to evaluate performance on test cases applicable to your scenario or domain.
"},{"location":"trulens_eval/custom_feedback_functions/","title":"Custom Functions","text":"In\u00a0[\u00a0]: Copied!
from trulens_eval import Provider, Feedback, Select, Tru\n\nclass StandAlone(Provider):\n def custom_feedback(self, my_text_field: str) -> float:\n\"\"\"\n A dummy function of text inputs to float outputs.\n\n Parameters:\n my_text_field (str): Text to evaluate.\n\n Returns:\n float: square length of the text\n \"\"\"\n return 1.0 / (1.0 + len(my_text_field) * len(my_text_field))\n
from trulens_eval import Provider, Feedback, Select, Tru class StandAlone(Provider): def custom_feedback(self, my_text_field: str) -> float: \"\"\" A dummy function of text inputs to float outputs. Parameters: my_text_field (str): Text to evaluate. Returns: float: square length of the text \"\"\" return 1.0 / (1.0 + len(my_text_field) * len(my_text_field))
- Instantiate your provider and feedback functions. The feedback function is wrapped by the trulens-eval Feedback class which helps specify what will get sent to your function parameters (For example: Select.RecordInput or Select.RecordOutput)
In\u00a0[\u00a0]: Copied!
standalone = StandAlone()\nf_custom_function = Feedback(standalone.custom_feedback).on(\n my_text_field=Select.RecordOutput\n)\n
standalone = StandAlone() f_custom_function = Feedback(standalone.custom_feedback).on( my_text_field=Select.RecordOutput )
- Your feedback function is now ready to use just like the out of the box feedback functions. Below is an example of it being used.
In\u00a0[\u00a0]: Copied!
tru = Tru()\nfeedback_results = tru.run_feedback_functions(\n record=record,\n feedback_functions=[f_custom_function]\n)\ntru.add_feedbacks(feedback_results)\n
tru = Tru() feedback_results = tru.run_feedback_functions( record=record, feedback_functions=[f_custom_function] ) tru.add_feedbacks(feedback_results) In\u00a0[\u00a0]: Copied!
multi_output_feedback = Feedback(lambda input_param: {'output_key1': 0.1, 'output_key2': 0.9}, name=\"multi\").on(\n input_param=Select.RecordOutput\n)\nfeedback_results = tru.run_feedback_functions(\n record=record,\n feedback_functions=[multi_output_feedback]\n)\ntru.add_feedbacks(feedback_results)\n multi_output_feedback = Feedback(lambda input_param: {'output_key1': 0.1, 'output_key2': 0.9}, name=\"multi\").on( input_param=Select.RecordOutput ) feedback_results = tru.run_feedback_functions( record=record, feedback_functions=[multi_output_feedback] ) tru.add_feedbacks(feedback_results) In\u00a0[\u00a0]: Copied!
# Aggregators will run on the same dict keys.\nimport numpy as np\nmulti_output_feedback = Feedback(lambda input_param: {'output_key1': 0.1, 'output_key2': 0.9}, name=\"multi-agg\").on(\n input_param=Select.RecordOutput\n).aggregate(np.mean)\nfeedback_results = tru.run_feedback_functions(\n record=record,\n feedback_functions=[multi_output_feedback]\n)\ntru.add_feedbacks(feedback_results)\n # Aggregators will run on the same dict keys. import numpy as np multi_output_feedback = Feedback(lambda input_param: {'output_key1': 0.1, 'output_key2': 0.9}, name=\"multi-agg\").on( input_param=Select.RecordOutput ).aggregate(np.mean) feedback_results = tru.run_feedback_functions( record=record, feedback_functions=[multi_output_feedback] ) tru.add_feedbacks(feedback_results) In\u00a0[\u00a0]: Copied!
# For multi-context chunking, an aggregator can operate on a list of multi output dictionaries.\ndef dict_aggregator(list_dict_input):\n agg = 0\n for dict_input in list_dict_input:\n agg += dict_input['output_key1']\n return agg\nmulti_output_feedback = Feedback(lambda input_param: {'output_key1': 0.1, 'output_key2': 0.9}, name=\"multi-agg-dict\").on(\n input_param=Select.RecordOutput\n).aggregate(dict_aggregator)\nfeedback_results = tru.run_feedback_functions(\n record=record,\n feedback_functions=[multi_output_feedback]\n)\ntru.add_feedbacks(feedback_results)\n # For multi-context chunking, an aggregator can operate on a list of multi output dictionaries. def dict_aggregator(list_dict_input): agg = 0 for dict_input in list_dict_input: agg += dict_input['output_key1'] return agg multi_output_feedback = Feedback(lambda input_param: {'output_key1': 0.1, 'output_key2': 0.9}, name=\"multi-agg-dict\").on( input_param=Select.RecordOutput ).aggregate(dict_aggregator) feedback_results = tru.run_feedback_functions( record=record, feedback_functions=[multi_output_feedback] ) tru.add_feedbacks(feedback_results)"},{"location":"trulens_eval/custom_feedback_functions/#custom-functions","title":"Custom Functions\u00b6","text":"
Feedback functions are an extensible framework for evaluating LLMs. You can add your own feedback functions to evaluate the qualities required by your application by updating trulens_eval/feedback.py, or simply creating a new provider class and feedback function in youre notebook. If your contributions would be useful for others, we encourage you to contribute to TruLens!
Feedback functions are organized by model provider into Provider classes.
The process for adding new feedback functions is:
- Create a new Provider class or locate an existing one that applies to your feedback function. If your feedback function does not rely on a model provider, you can create a standalone class. Add the new feedback function method to your selected class. Your new method can either take a single text (str) as a parameter or both prompt (str) and response (str). It should return a float between 0 (worst) and 1 (best).
"},{"location":"trulens_eval/custom_feedback_functions/#multi-output-feedback-functions","title":"Multi-Output Feedback functions\u00b6","text":"
Trulens also supports multi-output feedback functions. As a typical feedback function will output a float between 0 and 1, multi-output should output a dictionary of output_key to a float between 0 and 1. The feedbacks table will display the feedback with column feedback_name:::outputkey
"},{"location":"trulens_eval/feedback_function_guide/","title":"Feedback Functions","text":"
The Feedback class contains the starting point for feedback function specification and evaluation. A typical use-case looks like this:
from trulens_eval import feedback, Select, Feedback\n\nhugs = feedback.Huggingface()\n\nf_lang_match = Feedback(hugs.language_match)\n .on_input_output()\n
The components of this specifications are:
-
Provider classes -- feedback.OpenAI contains feedback function implementations like qs_relevance. Other classes subtyping feedback.Provider include Huggingface and Cohere.
-
Feedback implementations -- openai.qs_relevance is a feedback function implementation. Feedback implementations are simple callables that can be run on any arguments matching their signatures. In the example, the implementation has the following signature:
def language_match(self, text1: str, text2: str) -> float:\n
That is, language_match is a plain python method that accepts two pieces of text, both strings, and produces a float (assumed to be between 0.0 and 1.0).
-
Feedback constructor -- The line Feedback(openai.language_match) constructs a Feedback object with a feedback implementation.
-
Argument specification -- The next line, on_input_output, specifies how the language_match arguments are to be determined from an app record or app definition. The general form of this specification is done using on but several shorthands are provided. on_input_output states that the first two argument to language_match (text1 and text2) are to be the main app input and the main output, respectively.
Several utility methods starting with .on provide shorthands:
- `on_input(arg) == on_prompt(arg: Optional[str])` -- both specify that the next\nunspecified argument or `arg` should be the main app input.\n\n- `on_output(arg) == on_response(arg: Optional[str])` -- specify that the next\nargument or `arg` should be the main app output.\n\n- `on_input_output() == on_input().on_output()` -- specifies that the first\ntwo arguments of implementation should be the main app input and main app\noutput, respectively.\n\n- `on_default()` -- depending on signature of implementation uses either\n`on_output()` if it has a single argument, or `on_input_output` if it has\ntwo arguments.\n\nSome wrappers include additional shorthands:\n\n### llama_index-specific selectors\n\n- `TruLlama.select_source_nodes()` -- outputs the selector of the source\n documents part of the engine output.\n
"},{"location":"trulens_eval/feedback_function_guide/#fine-grained-selection-and-aggregation","title":"Fine-grained Selection and Aggregation","text":"
For more advanced control on the feedback function operation, we allow data selection and aggregation. Consider this feedback example:
f_qs_relevance = Feedback(openai.qs_relevance)\n .on_input()\n .on(Select.Record.app.combine_docs_chain._call.args.inputs.input_documents[:].page_content)\n .aggregate(numpy.min)\n\n# Implementation signature:\n# def qs_relevance(self, question: str, statement: str) -> float:\n
-
Argument Selection specification -- Where we previously set, on_input_output , the on(Select...) line enables specification of where the statement argument to the implementation comes from. The form of the specification will be discussed in further details in the Specifying Arguments section.
-
Aggregation specification -- The last line aggregate(numpy.min) specifies how feedback outputs are to be aggregated. This only applies to cases where the argument specification names more than one value for an input. The second specification, for statement was of this type. The input to aggregate must be a method which can be imported globally. This requirement is further elaborated in the next section. This function is called on the float results of feedback function evaluations to produce a single float. The default is numpy.mean.
The result of these lines is that f_qs_relevance can be now be run on app/records and will automatically select the specified components of those apps/records:
record: Record = ...\napp: App = ...\n\nfeedback_result: FeedbackResult = f_qs_relevance.run(app=app, record=record)\n
The object can also be provided to an app wrapper for automatic evaluation:
app: App = tru.Chain(...., feedbacks=[f_qs_relevance])\n
"},{"location":"trulens_eval/feedback_function_guide/#specifying-implementation-function-and-aggregate","title":"Specifying Implementation Function and Aggregate","text":"
The function or method provided to the Feedback constructor is the implementation of the feedback function which does the actual work of producing a float indicating some quantity of interest.
Note regarding FeedbackMode.DEFERRED -- Any function or method (not static or class methods presently supported) can be provided here but there are additional requirements if your app uses the \"deferred\" feedback evaluation mode (when feedback_mode=FeedbackMode.DEFERRED are specified to app constructor). In those cases the callables must be functions or methods that are importable (see the next section for details). The function/method performing the aggregation has the same requirements.
"},{"location":"trulens_eval/feedback_function_guide/#import-requirement-deferred-feedback-mode-only","title":"Import requirement (DEFERRED feedback mode only)","text":"
If using deferred evaluation, the feedback function implementations and aggregation implementations must be functions or methods from a Provider subclass that is importable. That is, the callables must be accessible were you to evaluate this code:
from somepackage.[...] import someproviderclass\nfrom somepackage.[...] import somefunction\n\n# [...] means optionally further package specifications\n\nprovider = someproviderclass(...) # constructor arguments can be included\nfeedback_implementation1 = provider.somemethod\nfeedback_implementation2 = somefunction\n
For provided feedback functions, somepackage is trulens_eval.feedback and someproviderclass is OpenAI or one of the other Provider subclasses. Custom feedback functions likewise need to be importable functions or methods of a provider subclass that can be imported. Critically, functions or classes defined locally in a notebook will not be importable this way.
"},{"location":"trulens_eval/feedback_function_guide/#specifying-arguments","title":"Specifying Arguments","text":"
The mapping between app/records to feedback implementation arguments is specified by the on... methods of the Feedback objects. The general form is:
feedback: Feedback = feedback.on(argname1=selector1, argname2=selector2, ...)\n
That is, Feedback.on(...) returns a new Feedback object with additional argument mappings, the source of argname1 is selector1 and so on for further argument names. The types of selector1 is JSONPath which we elaborate on in the \"Selector Details\".
If argument names are ommitted, they are taken from the feedback function implementation signature in order. That is,
Feedback(...).on(argname1=selector1, argname2=selector2)\n
and
Feedback(...).on(selector1, selector2)\n
are equivalent assuming the feedback implementation has two arguments, argname1 and argname2, in that order.
"},{"location":"trulens_eval/feedback_function_guide/#running-feedback","title":"Running Feedback","text":"
Feedback implementations are simple callables that can be run on any arguments matching their signatures. However, once wrapped with Feedback, they are meant to be run on outputs of app evaluation (the \"Records\"). Specifically, Feedback.run has this definition:
def run(self, \n app: Union[AppDefinition, JSON], \n record: Record\n) -> FeedbackResult:\n
That is, the context of a Feedback evaluation is an app (either as AppDefinition or a JSON-like object) and a Record of the execution of the aforementioned app. Both objects are indexable using \"Selectors\". By indexable here we mean that their internal components can be specified by a Selector and subsequently that internal component can be extracted using that selector. Selectors for Feedback start by specifying whether they are indexing into an App or a Record via the __app__ and __record__ special attributes (see Selectors section below).
"},{"location":"trulens_eval/feedback_function_guide/#selector-details","title":"Selector Details","text":"
Apps and Records will be converted to JSON-like structures representing their callstack.
Selectors are of type JSONPath defined in utils/serial.py help specify paths into JSON-like structures (enumerating Record or App contents).
In most cases, the Select object produces only a single item but can also address multiple items.
You can access the JSON structure with with_record methods and then calling layout_calls_as_app.
for example
response = my_llm_app(query)\n\nfrom trulens_eval import TruChain\ntru_recorder = TruChain(\n my_llm_app,\n app_id='Chain1_ChatApplication')\n\nresponse, tru_record = tru_recorder.with_record(my_llm_app, query)\njson_like = tru_record.layout_calls_as_app()\n
If a selector looks like the below
Select.Record.app.combine_documents_chain._call\n
It can be accessed via the JSON-like via
json_like['app']['combine_documents_chain']['_call']\n
The top level record also contains these helper accessors
-
RecordInput = Record.main_input -- points to the main input part of a Record. This is the first argument to the root method of an app (for langchain Chains this is the __call__ method).
-
RecordOutput = Record.main_output -- points to the main output part of a Record. This is the output of the root method of an app (i.e. __call__ for langchain Chains).
-
RecordCalls = Record.app -- points to the root of the app-structured mirror of calls in a record. See App-organized Calls Section above.
"},{"location":"trulens_eval/feedback_function_guide/#multiple-inputs-per-argument","title":"Multiple Inputs Per Argument","text":"
As in the f_qs_relevance example, a selector for a single argument may point to more than one aspect of a record/app. These are specified using the slice or lists in key/index poisitions. In that case, the feedback function is evaluated multiple times, its outputs collected, and finally aggregated into a main feedback result.
The collection of values for each argument of feedback implementation is collected and every combination of argument-to-value mapping is evaluated with a feedback definition. This may produce a large number of evaluations if more than one argument names multiple values. In the dashboard, all individual invocations of a feedback implementation are shown alongside the final aggregate result.
"},{"location":"trulens_eval/feedback_function_guide/#apprecord-organization-what-can-be-selected","title":"App/Record Organization (What can be selected)","text":"
The top level JSON attributes are defined by the class structures.
For a Record:
class Record(SerialModel):\n record_id: RecordID\n app_id: AppID\n\n cost: Optional[Cost] = None\n perf: Optional[Perf] = None\n\n ts: datetime = pydantic.Field(default_factory=lambda: datetime.now())\n\n tags: str = \"\"\n\n main_input: Optional[JSON] = None\n main_output: Optional[JSON] = None # if no error\n main_error: Optional[JSON] = None # if error\n\n # The collection of calls recorded. Note that these can be converted into a\n # json structure with the same paths as the app that generated this record\n # via `layout_calls_as_app`.\n calls: Sequence[RecordAppCall] = []\n
For an App:
class AppDefinition(SerialModel, WithClassInfo, ABC):\n ...\n\n app_id: AppID\n\n feedback_definitions: Sequence[FeedbackDefinition] = []\n\n feedback_mode: FeedbackMode = FeedbackMode.WITH_APP_THREAD\n\n root_class: Class\n\n root_callable: ClassVar[FunctionOrMethod]\n\n app: JSON\n
For your app, you can inspect the JSON-like structure by using the dict method:
tru = ... # your app, extending App\nprint(tru.dict())\n
"},{"location":"trulens_eval/feedback_function_guide/#calls-made-by-app-components","title":"Calls made by App Components","text":"
When evaluating a feedback function, Records are augmented with app/component calls. For example, if the instrumented app contains a component combine_docs_chain then app.combine_docs_chain will contain calls to methods of this component. app.combine_docs_chain._call will contain a RecordAppCall (see schema.py) with information about the inputs/outputs/metadata regarding the _call call to that component. Selecting this information is the reason behind the Select.RecordCalls alias.
You can inspect the components making up your app via the App method print_instrumented.
"},{"location":"trulens_eval/function_definitions/","title":"Function Definitions","text":"
A feedback function scores the output of an LLM application by analyzing generated text as part of an LLM application (or a downstream model or application built on it). This guide provides details about the feedback functions that are implemented out of the box by TruLens. At the end of the guide, you can find additional information about how to create custom feedback functions.
See also: https://www.trulens.org/trulens_eval/api/feedback/
"},{"location":"trulens_eval/function_definitions/#relevance","title":"Relevance","text":"
This evaluates the relevance of the LLM response to the given text by LLM prompting.
Relevance is currently only available with OpenAI ChatCompletion API.
TruLens offers two particular flavors of relevance:
-
Prompt response relevance is best for measuring the relationship of the final answer to the user inputed question. This flavor of relevance is particularly optimized for the following features:
- Relevance requires adherence to the entire prompt.
- Responses that don't provide a definitive answer can still be relevant
- Admitting lack of knowledge and refusals are still relevant.
- Feedback mechanism should differentiate between seeming and actual relevance.
- Relevant but inconclusive statements should get increasingly high scores as they are more helpful for answering the query.
You can read more information about the performance of prompt response relevance by viewing its smoke test results.
-
Question statement relevance, sometimes known as context relevance, is best for measuring the relationship of a provided context to the user inputed question. This flavor of relevance is optimized for a slightly different set of features:
- Relevance requires adherence to the entire query.
- Long context with small relevant chunks are relevant.
- Context that provides no answer can still be relevant.
- Feedback mechanism should differentiate between seeming and actual relevance.
- Relevant but inconclusive statements should get increasingly high scores as they are more helpful for answering the query.
You can read more information about the performance of question statement relevance by viewing its smoke test results.
"},{"location":"trulens_eval/function_definitions/#groundedness","title":"Groundedness","text":"
Groundedness uses OpenAI LLMs or Huggingface NLI to attempt to check if an answer is grounded in its supplied contexts on a scale from 1 to 10. The information overlap or entailment between source and response is then measured, choosing the highest score between sources and then averaged and scaled from 0 to 1.
You can read about the performance of groundedness evaluations by viewing its smoke test results.
"},{"location":"trulens_eval/function_definitions/#sentiment","title":"Sentiment","text":"
This evaluates the positive sentiment of either the prompt or response.
Sentiment is currently available to use with OpenAI, HuggingFace or Cohere as the model provider.
- The OpenAI sentiment feedback function prompts a Chat Completion model to rate the sentiment from 1 to 10, and then scales the response down to 0-1.
- The HuggingFace sentiment feedback function returns a raw score from 0 to 1.
- The Cohere sentiment feedback function uses the classification endpoint and a small set of examples stored in
feedback_prompts.py to return either a 0 or a 1.
"},{"location":"trulens_eval/function_definitions/#model-agreement","title":"Model Agreement","text":"
Model agreement uses OpenAI to attempt an honest answer at your prompt with system prompts for correctness, and then evaluates the agreement of your LLM response to this model on a scale from 1 to 10. The agreement with each honest bot is then averaged and scaled from 0 to 1.
"},{"location":"trulens_eval/function_definitions/#language-match","title":"Language Match","text":"
This evaluates if the language of the prompt and response match.
Language match is currently only available to use with HuggingFace as the model provider. This feedback function returns a score in the range from 0 to 1, where 1 indicates match and 0 indicates mismatch.
"},{"location":"trulens_eval/function_definitions/#toxicity","title":"Toxicity","text":"
This evaluates the toxicity of the prompt or response.
Toxicity is currently only available to be used with HuggingFace, and uses a classification endpoint to return a score from 0 to 1. The feedback function is negated as not_toxicity, and returns a 1 if not toxic and a 0 if toxic.
"},{"location":"trulens_eval/function_definitions/#moderation","title":"Moderation","text":"
The OpenAI Moderation API is made available for use as feedback functions. This includes hate, hate/threatening, self-harm, sexual, sexual/minors, violence, and violence/graphic. Each is negated (ex: not_hate) so that a 0 would indicate that the moderation rule is violated. These feedback functions return a score in the range 0 to 1.
"},{"location":"trulens_eval/function_definitions/#stereotypes","title":"Stereotypes","text":"
This evaluates stereotypes using OpenAI LLMs to check if gender or race were assumed with no prior indication. This is rated on a scale from 1 to 10 where 10 being no new gender or race assumptions. A two indicates gender or race assumption with no indication, and a one indicates gender or race changes with prior indication that is different.
"},{"location":"trulens_eval/function_definitions/#summarization","title":"Summarization","text":"
This evaluates summarization tasks using OpenAI LLMs to check how well a summarization hits upon main points. This is rated on a scale from 1 to 10 where 10 being all points are addressed.
"},{"location":"trulens_eval/function_definitions/#embeddings-distance","title":"Embeddings Distance","text":"
Given an embedder, as is typical in vector DBs, this evaluates the distance of the query and document embeddings. Currently supporting cosine distance, L1/Manhattan distance, and L2/Euclidean distance.
"},{"location":"trulens_eval/gh_top_intro/","title":"Gh top intro","text":""},{"location":"trulens_eval/gh_top_intro/#welcome-to-trulens","title":"\ud83e\udd91 Welcome to TruLens!","text":"
TruLens provides a set of tools for developing and monitoring neural nets, including large language models. This includes both tools for evaluation of LLMs and LLM-based applications with TruLens-Eval and deep learning explainability with TruLens-Explain. TruLens-Eval and TruLens-Explain are housed in separate packages and can be used independently.
The best way to support TruLens is to give us a \u2b50 and join our slack community!
"},{"location":"trulens_eval/gh_top_intro/#trulens-eval","title":"TruLens-Eval","text":"
TruLens-Eval contains instrumentation and evaluation tools for large language model (LLM) based applications. It supports the iterative development and monitoring of a wide range of LLM applications by wrapping your application to log key metadata across the entire chain (or off chain if your project does not use chains) on your local machine. Importantly, it also gives you the tools you need to evaluate the quality of your LLM-based applications.
TruLens-Eval has two key value propositions:
- Evaluation:
- TruLens supports the evaluation of inputs, outputs and internals of your LLM application using any model (including LLMs).
- A number of feedback functions for evaluation are implemented out-of-the-box such as groundedness, relevance and toxicity. The framework is also easily extensible for custom evaluation requirements.
- Tracking:
- TruLens contains instrumentation for any LLM application including question answering, retrieval-augmented generation, agent-based applications and more. This instrumentation allows for the tracking of a wide variety of usage metrics and metadata. Read more in the instrumentation overview.
- TruLens' instrumentation can be applied to any LLM application without being tied down to a given framework. Additionally, deep integrations with LangChain and Llama-Index allow the capture of internal metadata and text.
- Anything that is tracked by the instrumentation can be evaluated!
The process for building your evaluated and tracked LLM application with TruLens is shown below \ud83d\udc47
"},{"location":"trulens_eval/gh_top_intro/#installation-and-setup","title":"Installation and setup","text":"
Install trulens-eval from PyPI.
pip install trulens-eval\n
"},{"location":"trulens_eval/gh_top_intro/#quick-usage","title":"Quick Usage","text":"
TruLens supports the evaluation of tracking for any LLM app framework. Choose a framework below to get started:
Langchain
langchain_quickstart.ipynb.
Llama-Index
llama_index_quickstart.ipynb.
Custom Text to Text Apps
text2text_quickstart.ipynb.
"},{"location":"trulens_eval/groundedness_smoke_tests/","title":"Groundedness","text":"In\u00a0[1]: Copied!
# Import groundedness feedback function\nfrom trulens_eval.feedback import GroundTruthAgreement, Groundedness\nfrom trulens_eval import TruBasicApp, Feedback, Tru, Select\nfrom test_cases import generate_summeval_groundedness_golden_set\n\nTru().reset_database()\n\n# generator for groundedness golden set\ntest_cases_gen = generate_summeval_groundedness_golden_set(\"./datasets/summeval_test_100.json\")\n\n# generate x number of test cases\ngroundedness_golden_set = []\nfor i in range(50):\n groundedness_golden_set.append(next(test_cases_gen))\n
# Import groundedness feedback function from trulens_eval.feedback import GroundTruthAgreement, Groundedness from trulens_eval import TruBasicApp, Feedback, Tru, Select from test_cases import generate_summeval_groundedness_golden_set Tru().reset_database() # generator for groundedness golden set test_cases_gen = generate_summeval_groundedness_golden_set(\"./datasets/summeval_test_100.json\") # generate x number of test cases groundedness_golden_set = [] for i in range(50): groundedness_golden_set.append(next(test_cases_gen))
\ud83e\udd91 Tru initialized with db url sqlite:///default.sqlite .\n\ud83d\uded1 Secret keys may be written to the database. See the `database_redact_keys` option of `Tru` to prevent this.\nDeleted 0 rows.\n
In\u00a0[2]: Copied!
groundedness_golden_set[:3]\n
groundedness_golden_set[:3] Out[2]:
[{'query': '(CNN)Donald Sterling\\'s racist remarks cost him an NBA team last year. But now it\\'s his former female companion who has lost big. A Los Angeles judge has ordered V. Stiviano to pay back more than $2.6 million in gifts after Sterling\\'s wife sued her. In the lawsuit, Rochelle \"Shelly\" Sterling accused Stiviano of targeting extremely wealthy older men. She claimed Donald Sterling used the couple\\'s money to buy Stiviano a Ferrari, two Bentleys and a Range Rover, and that he helped her get a $1.8 million duplex. Who is V. Stiviano? Stiviano countered that there was nothing wrong with Donald Sterling giving her gifts and that she never took advantage of the former Los Angeles Clippers owner, who made much of his fortune in real estate. Shelly Sterling was thrilled with the court decision Tuesday, her lawyer told CNN affiliate KABC. \"This is a victory for the Sterling family in recovering the $2,630,000 that Donald lavished on a conniving mistress,\" attorney Pierce O\\'Donnell said in a statement. \"It also sets a precedent that the injured spouse can recover damages from the recipient of these ill-begotten gifts.\" Stiviano\\'s gifts from Donald Sterling didn\\'t just include uber-expensive items like luxury cars. According to the Los Angeles Times, the list also includes a $391 Easter bunny costume, a $299 two-speed blender and a $12 lace thong. Donald Sterling\\'s downfall came after an audio recording surfaced of the octogenarian arguing with Stiviano. In the tape, Sterling chastises Stiviano for posting pictures on social media of her posing with African-Americans, including basketball legend Magic Johnson. \"In your lousy f**ing Instagrams, you don\\'t have to have yourself with -- walking with black people,\" Sterling said in the audio first posted by TMZ. He also tells Stiviano not to bring Johnson to Clippers games and not to post photos with the Hall of Famer so Sterling\\'s friends can see. \"Admire him, bring him here, feed him, f**k him, but don\\'t put (Magic) on an Instagram for the world to have to see so they have to call me,\" Sterling said. NBA Commissioner Adam Silver banned Sterling from the league, fined him $2.5 million and pushed through a charge to terminate all of his ownership rights in the franchise. Fact check: Donald Sterling\\'s claims vs. reality CNN\\'s Dottie Evans contributed to this report.',\n 'response': \"donald sterling , nba team last year . sterling 's wife sued for $ 2.6 million in gifts . sterling says he is the former female companion who has lost the . sterling has ordered v. stiviano to pay back $ 2.6 m in gifts after his wife sued . sterling also includes a $ 391 easter bunny costume , $ 299 and a $ 299 .\",\n 'expected_score': 0.27},\n {'query': '(CNN)Donald Sterling\\'s racist remarks cost him an NBA team last year. But now it\\'s his former female companion who has lost big. A Los Angeles judge has ordered V. Stiviano to pay back more than $2.6 million in gifts after Sterling\\'s wife sued her. In the lawsuit, Rochelle \"Shelly\" Sterling accused Stiviano of targeting extremely wealthy older men. She claimed Donald Sterling used the couple\\'s money to buy Stiviano a Ferrari, two Bentleys and a Range Rover, and that he helped her get a $1.8 million duplex. Who is V. Stiviano? Stiviano countered that there was nothing wrong with Donald Sterling giving her gifts and that she never took advantage of the former Los Angeles Clippers owner, who made much of his fortune in real estate. Shelly Sterling was thrilled with the court decision Tuesday, her lawyer told CNN affiliate KABC. \"This is a victory for the Sterling family in recovering the $2,630,000 that Donald lavished on a conniving mistress,\" attorney Pierce O\\'Donnell said in a statement. \"It also sets a precedent that the injured spouse can recover damages from the recipient of these ill-begotten gifts.\" Stiviano\\'s gifts from Donald Sterling didn\\'t just include uber-expensive items like luxury cars. According to the Los Angeles Times, the list also includes a $391 Easter bunny costume, a $299 two-speed blender and a $12 lace thong. Donald Sterling\\'s downfall came after an audio recording surfaced of the octogenarian arguing with Stiviano. In the tape, Sterling chastises Stiviano for posting pictures on social media of her posing with African-Americans, including basketball legend Magic Johnson. \"In your lousy f**ing Instagrams, you don\\'t have to have yourself with -- walking with black people,\" Sterling said in the audio first posted by TMZ. He also tells Stiviano not to bring Johnson to Clippers games and not to post photos with the Hall of Famer so Sterling\\'s friends can see. \"Admire him, bring him here, feed him, f**k him, but don\\'t put (Magic) on an Instagram for the world to have to see so they have to call me,\" Sterling said. NBA Commissioner Adam Silver banned Sterling from the league, fined him $2.5 million and pushed through a charge to terminate all of his ownership rights in the franchise. Fact check: Donald Sterling\\'s claims vs. reality CNN\\'s Dottie Evans contributed to this report.',\n 'response': \"donald sterling accused stiviano of targeting extremely wealthy older men . she claimed donald sterling used the couple 's money to buy stiviano a ferrari , two bentleys and a range rover . stiviano countered that there was nothing wrong with donald sterling giving her gifts .\",\n 'expected_score': 0.4},\n {'query': '(CNN)Donald Sterling\\'s racist remarks cost him an NBA team last year. But now it\\'s his former female companion who has lost big. A Los Angeles judge has ordered V. Stiviano to pay back more than $2.6 million in gifts after Sterling\\'s wife sued her. In the lawsuit, Rochelle \"Shelly\" Sterling accused Stiviano of targeting extremely wealthy older men. She claimed Donald Sterling used the couple\\'s money to buy Stiviano a Ferrari, two Bentleys and a Range Rover, and that he helped her get a $1.8 million duplex. Who is V. Stiviano? Stiviano countered that there was nothing wrong with Donald Sterling giving her gifts and that she never took advantage of the former Los Angeles Clippers owner, who made much of his fortune in real estate. Shelly Sterling was thrilled with the court decision Tuesday, her lawyer told CNN affiliate KABC. \"This is a victory for the Sterling family in recovering the $2,630,000 that Donald lavished on a conniving mistress,\" attorney Pierce O\\'Donnell said in a statement. \"It also sets a precedent that the injured spouse can recover damages from the recipient of these ill-begotten gifts.\" Stiviano\\'s gifts from Donald Sterling didn\\'t just include uber-expensive items like luxury cars. According to the Los Angeles Times, the list also includes a $391 Easter bunny costume, a $299 two-speed blender and a $12 lace thong. Donald Sterling\\'s downfall came after an audio recording surfaced of the octogenarian arguing with Stiviano. In the tape, Sterling chastises Stiviano for posting pictures on social media of her posing with African-Americans, including basketball legend Magic Johnson. \"In your lousy f**ing Instagrams, you don\\'t have to have yourself with -- walking with black people,\" Sterling said in the audio first posted by TMZ. He also tells Stiviano not to bring Johnson to Clippers games and not to post photos with the Hall of Famer so Sterling\\'s friends can see. \"Admire him, bring him here, feed him, f**k him, but don\\'t put (Magic) on an Instagram for the world to have to see so they have to call me,\" Sterling said. NBA Commissioner Adam Silver banned Sterling from the league, fined him $2.5 million and pushed through a charge to terminate all of his ownership rights in the franchise. Fact check: Donald Sterling\\'s claims vs. reality CNN\\'s Dottie Evans contributed to this report.',\n 'response': \"a los angeles judge has ordered v. stiviano to pay back more than $ 2.6 million in gifts after sterling 's wife sued her . -lrb- cnn -rrb- donald sterling 's racist remarks cost him an nba team last year . but now it 's his former female companion who has lost big . who is v. stiviano ? .\",\n 'expected_score': 0.7}] In\u00a0[3]: Copied!
import os\nos.environ[\"OPENAI_API_KEY\"] = \"...\"\nos.environ[\"HUGGINGFACE_API_KEY\"] = \"...\"\n
import os os.environ[\"OPENAI_API_KEY\"] = \"...\" os.environ[\"HUGGINGFACE_API_KEY\"] = \"...\" In\u00a0[4]: Copied!
from trulens_eval.feedback.provider.hugs import Huggingface\nfrom trulens_eval.feedback.provider import OpenAI\nimport numpy as np\n\nhuggingface_provider = Huggingface()\ngroundedness_hug = Groundedness(groundedness_provider=huggingface_provider)\nf_groundedness_hug = Feedback(groundedness_hug.groundedness_measure, name = \"Groundedness Huggingface\").on_input().on_output().aggregate(groundedness_hug.grounded_statements_aggregator)\ndef wrapped_groundedness_hug(input, output):\n return np.mean(list(f_groundedness_hug(input, output)[0].values()))\n \n \n \ngroundedness_openai = Groundedness(groundedness_provider=OpenAI(model_engine=\"gpt-3.5-turbo\")) # GPT-3.5-turbot being the default model if not specified\nf_groundedness_openai = Feedback(groundedness_openai.groundedness_measure, name = \"Groundedness OpenAI GPT-3.5\").on_input().on_output().aggregate(groundedness_openai.grounded_statements_aggregator)\ndef wrapped_groundedness_openai(input, output):\n return f_groundedness_openai(input, output)[0]['full_doc_score']\n\ngroundedness_openai_gpt4 = Groundedness(groundedness_provider=OpenAI(model_engine=\"gpt-4\"))\nf_groundedness_openai_gpt4 = Feedback(groundedness_openai_gpt4.groundedness_measure, name = \"Groundedness OpenAI GPT-4\").on_input().on_output().aggregate(groundedness_openai_gpt4.grounded_statements_aggregator)\ndef wrapped_groundedness_openai_gpt4(input, output):\n return f_groundedness_openai_gpt4(input, output)[0]['full_doc_score']\n
from trulens_eval.feedback.provider.hugs import Huggingface from trulens_eval.feedback.provider import OpenAI import numpy as np huggingface_provider = Huggingface() groundedness_hug = Groundedness(groundedness_provider=huggingface_provider) f_groundedness_hug = Feedback(groundedness_hug.groundedness_measure, name = \"Groundedness Huggingface\").on_input().on_output().aggregate(groundedness_hug.grounded_statements_aggregator) def wrapped_groundedness_hug(input, output): return np.mean(list(f_groundedness_hug(input, output)[0].values())) groundedness_openai = Groundedness(groundedness_provider=OpenAI(model_engine=\"gpt-3.5-turbo\")) # GPT-3.5-turbot being the default model if not specified f_groundedness_openai = Feedback(groundedness_openai.groundedness_measure, name = \"Groundedness OpenAI GPT-3.5\").on_input().on_output().aggregate(groundedness_openai.grounded_statements_aggregator) def wrapped_groundedness_openai(input, output): return f_groundedness_openai(input, output)[0]['full_doc_score'] groundedness_openai_gpt4 = Groundedness(groundedness_provider=OpenAI(model_engine=\"gpt-4\")) f_groundedness_openai_gpt4 = Feedback(groundedness_openai_gpt4.groundedness_measure, name = \"Groundedness OpenAI GPT-4\").on_input().on_output().aggregate(groundedness_openai_gpt4.grounded_statements_aggregator) def wrapped_groundedness_openai_gpt4(input, output): return f_groundedness_openai_gpt4(input, output)[0]['full_doc_score']
\u2705 In Groundedness Huggingface, input source will be set to __record__.main_input or `Select.RecordInput` .\n\u2705 In Groundedness Huggingface, input statement will be set to __record__.main_output or `Select.RecordOutput` .\n\u2705 In Groundedness OpenAI GPT-3.5, input source will be set to __record__.main_input or `Select.RecordInput` .\n\u2705 In Groundedness OpenAI GPT-3.5, input statement will be set to __record__.main_output or `Select.RecordOutput` .\n\u2705 In Groundedness OpenAI GPT-4, input source will be set to __record__.main_input or `Select.RecordInput` .\n\u2705 In Groundedness OpenAI GPT-4, input statement will be set to __record__.main_output or `Select.RecordOutput` .\n
In\u00a0[5]: Copied!
# Create a Feedback object using the numeric_difference method of the ground_truth object\nground_truth = GroundTruthAgreement(groundedness_golden_set)\n# Call the numeric_difference method with app and record and aggregate to get the mean absolute error\nf_mae = Feedback(ground_truth.mae, name = \"Mean Absolute Error\").on(Select.Record.calls[0].args.args[0]).on(Select.Record.calls[0].args.args[1]).on_output()\n
# Create a Feedback object using the numeric_difference method of the ground_truth object ground_truth = GroundTruthAgreement(groundedness_golden_set) # Call the numeric_difference method with app and record and aggregate to get the mean absolute error f_mae = Feedback(ground_truth.mae, name = \"Mean Absolute Error\").on(Select.Record.calls[0].args.args[0]).on(Select.Record.calls[0].args.args[1]).on_output()
\u2705 In Mean Absolute Error, input prompt will be set to __record__.calls[0].args.args[0] .\n\u2705 In Mean Absolute Error, input response will be set to __record__.calls[0].args.args[1] .\n\u2705 In Mean Absolute Error, input score will be set to __record__.main_output or `Select.RecordOutput` .\n
In\u00a0[6]: Copied!
tru_wrapped_groundedness_hug = TruBasicApp(wrapped_groundedness_hug, app_id = \"groundedness huggingface\", feedbacks=[f_mae])\ntru_wrapped_groundedness_openai = TruBasicApp(wrapped_groundedness_openai, app_id = \"groundedness openai gpt-3.5\", feedbacks=[f_mae])\ntru_wrapped_groundedness_openai_gpt4 = TruBasicApp(wrapped_groundedness_openai_gpt4, app_id = \"groundedness openai gpt-4\", feedbacks=[f_mae])\n
tru_wrapped_groundedness_hug = TruBasicApp(wrapped_groundedness_hug, app_id = \"groundedness huggingface\", feedbacks=[f_mae]) tru_wrapped_groundedness_openai = TruBasicApp(wrapped_groundedness_openai, app_id = \"groundedness openai gpt-3.5\", feedbacks=[f_mae]) tru_wrapped_groundedness_openai_gpt4 = TruBasicApp(wrapped_groundedness_openai_gpt4, app_id = \"groundedness openai gpt-4\", feedbacks=[f_mae])
\u2705 added app groundedness huggingface\n\u2705 added feedback definition feedback_definition_hash_ca9bbb2338965a9d34e17ae53f641d9c\n\u2705 added app groundedness openai\n\u2705 added feedback definition feedback_definition_hash_ca9bbb2338965a9d34e17ae53f641d9c\n\u2705 added app groundedness openai gpt4\n\u2705 added feedback definition feedback_definition_hash_ca9bbb2338965a9d34e17ae53f641d9c\n
In\u00a0[\u00a0]: Copied!
for i in range(len(groundedness_golden_set)):\n source = groundedness_golden_set[i][\"query\"]\n response = groundedness_golden_set[i][\"response\"]\n with tru_wrapped_groundedness_hug as recording:\n tru_wrapped_groundedness_hug.app(source, response)\n with tru_wrapped_groundedness_openai as recording:\n tru_wrapped_groundedness_openai.app(source, response)\n with tru_wrapped_groundedness_openai_gpt4 as recording:\n tru_wrapped_groundedness_openai_gpt4.app(source, response)\n
for i in range(len(groundedness_golden_set)): source = groundedness_golden_set[i][\"query\"] response = groundedness_golden_set[i][\"response\"] with tru_wrapped_groundedness_hug as recording: tru_wrapped_groundedness_hug.app(source, response) with tru_wrapped_groundedness_openai as recording: tru_wrapped_groundedness_openai.app(source, response) with tru_wrapped_groundedness_openai_gpt4 as recording: tru_wrapped_groundedness_openai_gpt4.app(source, response) In\u00a0[9]: Copied!
Tru().get_leaderboard(app_ids=[]).sort_values(by=\"Mean Absolute Error\")\n
Tru().get_leaderboard(app_ids=[]).sort_values(by=\"Mean Absolute Error\") Out[9]: Mean Absolute Error latency total_cost app_id groundedness huggingface 0.251471 2.4 0.000000 groundedness openai 2.371200 2.4 0.001344 groundedness openai gpt4 2.371200 2.4 0.001464"},{"location":"trulens_eval/groundedness_smoke_tests/#groundedness-evaluations","title":"Groundedness Evaluations\u00b6","text":"
In many ways, feedbacks can be thought of as LLM apps themselves. Given text, they return some result. Thinking in this way, we can use TruLens to evaluate and track our feedback quality. We can even do this for different models (e.g. gpt-3.5 and gpt-4) or prompting schemes (such as chain-of-thought reasoning).
This notebook follows an evaluation of a set of test cases generated from human annotated datasets. In particular, we generate test cases from SummEval.
SummEval is one of the datasets dedicated to automated evaluations on summarization tasks, which are closely related to the groundedness evaluation in RAG with the retrieved context (i.e. the source) and response (i.e. the summary). It contains human annotation of numerical score (1 to 5) comprised of scoring from 3 human expert annotators and 5 croweded-sourced annotators. There are 16 models being used for generation in total for 100 paragraphs in the test set, so there are a total of 16,000 machine-generated summaries. Each paragraph also has several human-written summaries for comparative analysis.
For evaluating groundedness feedback functions, we calculate the annotated \"relevance\" and \"consistency (aka factuality)\" scores with equal weights and normalized to 0 to 1 score to match the output of feedback functions.
"},{"location":"trulens_eval/groundedness_smoke_tests/#benchmarking-various-groundedness-feedback-function-providers-openai-gpt-35-turbo-vs-gpt-4-vs-huggingface","title":"Benchmarking various Groundedness feedback function providers (OpenAI GPT-3.5-turbo vs GPT-4 vs Huggingface)\u00b6","text":""},{"location":"trulens_eval/install/","title":"\ud83d\ude80 Installation","text":""},{"location":"trulens_eval/install/#getting-access-to-trulens","title":"Getting access to TruLens","text":"
These installation instructions assume that you have conda installed and added to your path.
-
Create a virtual environment (or modify an existing one).
conda create -n \"<my_name>\" python=3 # Skip if using existing environment.\nconda activate <my_name>\n
-
[Pip installation] Install the trulens-eval pip package from PyPI.
pip install trulens-eval\n
-
[Local installation] If you would like to develop or modify TruLens, you can download the source code by cloning the TruLens repo.
git clone https://github.com/truera/trulens.git\n
-
[Local installation] Install the TruLens repo.
cd trulens/trulens_eval\npip install -e .\n
"},{"location":"trulens_eval/intro/","title":"Welcome to TruLens-Eval!","text":"
Evaluate and track your LLM experiments with TruLens. As you work on your models and prompts TruLens-Eval supports the iterative development and of a wide range of LLM applications by wrapping your application to log key metadata across the entire chain (or off chain if your project does not use chains) on your local machine.
Using feedback functions, you can objectively evaluate the quality of the responses provided by an LLM to your requests. This is completed with minimal latency, as this is achieved in a sequential call for your application, and evaluations are logged to your local machine. Finally, we provide an easy to use Streamlit dashboard run locally on your machine for you to better understand your LLM\u2019s performance.
"},{"location":"trulens_eval/intro/#value-propositions","title":"Value Propositions","text":"
TruLens-Eval has two key value propositions:
- Evaluation:
- TruLens supports the evaluation of inputs, outputs and internals of your LLM application using any model (including LLMs).
- A number of feedback functions for evaluation are implemented out-of-the-box such as groundedness, relevance and toxicity. The framework is also easily extensible for custom evaluation requirements.
- Tracking:
- TruLens contains instrumentation for any LLM application including question answering, retrieval-augmented generation, agent-based applications and more. This instrumentation allows for the tracking of a wide variety of usage metrics and metadata. Read more in the instrumentation overview.
- TruLens' instrumentation can be applied to any LLM application without being tied down to a given framework. Additionally, deep integrations with LangChain and Llama-Index allow the capture of internal metadata and text.
- Anything that is tracked by the instrumentation can be evaluated!
The process for building your evaluated and tracked LLM application with TruLens is below \ud83d\udc47
"},{"location":"trulens_eval/intro/#installation-and-setup","title":"Installation and Setup","text":"
Install the trulens-eval pip package from PyPI.
pip install trulens-eval\n
"},{"location":"trulens_eval/intro/#setting-keys","title":"Setting Keys","text":"
In any of the quickstarts, you will need OpenAI and Huggingface keys. You can add keys by setting the environmental variables:
import os\nos.environ[\"OPENAI_API_KEY\"] = \"...\"\nos.environ[\"HUGGINGFACE_API_KEY\"] = \"...\"\n
"},{"location":"trulens_eval/intro/#quick-usage","title":"Quick Usage","text":"
TruLens supports the evaluation of tracking for any LLM app framework. Choose a framework below to get started:
Langchain
langchain_quickstart.ipynb.
Llama-Index
llama_index_quickstart.ipynb.
Custom Text to Text Apps
text2text_quickstart.ipynb.
"},{"location":"trulens_eval/intro/#contributing","title":"\ud83d\udca1 Contributing","text":"
Interested in contributing? See our contribution guide for more details.
"},{"location":"trulens_eval/langchain_instrumentation/","title":"LangChain Integration","text":"In\u00a0[\u00a0]: Copied!
# required imports\nfrom langchain.chains import LLMChain\nfrom langchain.llms import OpenAI\nfrom langchain.prompts.chat import HumanMessagePromptTemplate, ChatPromptTemplate, PromptTemplate\nfrom trulens_eval import TruChain\n\n# typical langchain setup\nfull_prompt = HumanMessagePromptTemplate(\n prompt=PromptTemplate(\n template=\n \"Provide a helpful response with relevant background information for the following: {prompt}\",\n input_variables=[\"prompt\"],\n )\n)\nchat_prompt_template = ChatPromptTemplate.from_messages([full_prompt])\n\nllm = OpenAI(temperature=0.9, max_tokens=128)\nchain = LLMChain(llm=llm, prompt=chat_prompt_template, verbose=True)\n # required imports from langchain.chains import LLMChain from langchain.llms import OpenAI from langchain.prompts.chat import HumanMessagePromptTemplate, ChatPromptTemplate, PromptTemplate from trulens_eval import TruChain # typical langchain setup full_prompt = HumanMessagePromptTemplate( prompt=PromptTemplate( template= \"Provide a helpful response with relevant background information for the following: {prompt}\", input_variables=[\"prompt\"], ) ) chat_prompt_template = ChatPromptTemplate.from_messages([full_prompt]) llm = OpenAI(temperature=0.9, max_tokens=128) chain = LLMChain(llm=llm, prompt=chat_prompt_template, verbose=True)
To instrument an LLM chain, all that's required is to wrap it using TruChain.
In\u00a0[\u00a0]: Copied!
# instrument with TruChain\ntru_recorder = TruChain(chain)\n
# instrument with TruChain tru_recorder = TruChain(chain)
You can find the full quickstart available here: LangChain Quickstart
In\u00a0[\u00a0]: Copied!
from langchain import LLMChain\nfrom langchain import PromptTemplate\nfrom langchain.callbacks import AsyncIteratorCallbackHandler\nfrom langchain.chains import LLMChain\nfrom langchain.chat_models.openai import ChatOpenAI\n\nfrom trulens_eval import TruChain\n\n# Set up an async callback.\ncallback = AsyncIteratorCallbackHandler()\n\n# Setup a simple question/answer chain with streaming ChatOpenAI.\nprompt = PromptTemplate.from_template(\"Honestly answer this question: {question}.\")\nllm = ChatOpenAI(\n temperature=0.0,\n streaming=True, # important\n callbacks=[callback] # callback can be here or below in acall_with_record\n)\nasync_chain = LLMChain(llm=llm, prompt=prompt)\n from langchain import LLMChain from langchain import PromptTemplate from langchain.callbacks import AsyncIteratorCallbackHandler from langchain.chains import LLMChain from langchain.chat_models.openai import ChatOpenAI from trulens_eval import TruChain # Set up an async callback. callback = AsyncIteratorCallbackHandler() # Setup a simple question/answer chain with streaming ChatOpenAI. prompt = PromptTemplate.from_template(\"Honestly answer this question: {question}.\") llm = ChatOpenAI( temperature=0.0, streaming=True, # important callbacks=[callback] # callback can be here or below in acall_with_record ) async_chain = LLMChain(llm=llm, prompt=prompt)
Once you have created the async LLM chain you can instrument it just as before.
In\u00a0[\u00a0]: Copied!
async_tc_recorder = TruChain(async_chain)\n\nwith async_tc_recorder as recording:\n await async_chain.acall(inputs=dict(question=\"What is 1+2? Explain your answer.\"))\n
async_tc_recorder = TruChain(async_chain) with async_tc_recorder as recording: await async_chain.acall(inputs=dict(question=\"What is 1+2? Explain your answer.\"))
For more usage examples, check out the LangChain examples directory.
"},{"location":"trulens_eval/langchain_instrumentation/#langchain-integration","title":"LangChain Integration\u00b6","text":"
TruLens provides TruChain, a deep integration with LangChain to allow you to inspect and evaluate the internals of your application built using LangChain.
TruChain captures all of the metrics and metadata listed in the instrumentation overview. In addition, TruChain instruments the following LangChain classes:
"},{"location":"trulens_eval/langchain_instrumentation/#instrumented-classes","title":"Instrumented Classes\u00b6","text":"
- langchain.chains.base.Chain
- langchain.vectorstores.base.BaseRetriever
- langchain.schema.BaseRetriever
- langchain.llms.base.BaseLLM
- langchain.prompts.base.BasePromptTemplate
- langchain.schema.BaseMemory
- langchain.schema.BaseChatMessageHistory
"},{"location":"trulens_eval/langchain_instrumentation/#example-usage","title":"Example Usage\u00b6","text":"
Below is a quick example of usage. First, we'll create a standard LLMChain.
"},{"location":"trulens_eval/langchain_instrumentation/#async-support","title":"Async Support\u00b6","text":"
TruChain also provides async support for Langchain through the acall method. This allows you to track and evaluate async and streaming LangChain applications.
As an example, below is an LLM chain set up with an async callback.
"},{"location":"trulens_eval/langchain_quickstart/","title":"Langchain Quickstart","text":"In\u00a0[\u00a0]: Copied!
# ! pip install trulens_eval==0.18.0 langchain>=0.0.335\n
# ! pip install trulens_eval==0.18.0 langchain>=0.0.335 In\u00a0[\u00a0]: Copied!
import os\nos.environ[\"OPENAI_API_KEY\"] = \"...\"\nos.environ[\"HUGGINGFACE_API_KEY\"] = \"...\"\n
import os os.environ[\"OPENAI_API_KEY\"] = \"...\" os.environ[\"HUGGINGFACE_API_KEY\"] = \"...\" In\u00a0[\u00a0]: Copied!
from IPython.display import JSON\n\n# Imports main tools:\nfrom trulens_eval import TruChain, Feedback, Huggingface, Tru\nfrom trulens_eval.schema import FeedbackResult\ntru = Tru()\n\n# Imports from langchain to build app. You may need to install langchain first\n# with the following:\n# ! pip install langchain>=0.0.170\nfrom langchain.chains import LLMChain\nfrom langchain.llms import OpenAI\nfrom langchain.prompts.chat import ChatPromptTemplate, PromptTemplate\nfrom langchain.prompts.chat import HumanMessagePromptTemplate\n
from IPython.display import JSON # Imports main tools: from trulens_eval import TruChain, Feedback, Huggingface, Tru from trulens_eval.schema import FeedbackResult tru = Tru() # Imports from langchain to build app. You may need to install langchain first # with the following: # ! pip install langchain>=0.0.170 from langchain.chains import LLMChain from langchain.llms import OpenAI from langchain.prompts.chat import ChatPromptTemplate, PromptTemplate from langchain.prompts.chat import HumanMessagePromptTemplate In\u00a0[\u00a0]: Copied!
full_prompt = HumanMessagePromptTemplate(\n prompt=PromptTemplate(\n template=\n \"Provide a helpful response with relevant background information for the following: {prompt}\",\n input_variables=[\"prompt\"],\n )\n)\n\nchat_prompt_template = ChatPromptTemplate.from_messages([full_prompt])\n\nllm = OpenAI(temperature=0.9, max_tokens=128)\n\nchain = LLMChain(llm=llm, prompt=chat_prompt_template, verbose=True)\n full_prompt = HumanMessagePromptTemplate( prompt=PromptTemplate( template= \"Provide a helpful response with relevant background information for the following: {prompt}\", input_variables=[\"prompt\"], ) ) chat_prompt_template = ChatPromptTemplate.from_messages([full_prompt]) llm = OpenAI(temperature=0.9, max_tokens=128) chain = LLMChain(llm=llm, prompt=chat_prompt_template, verbose=True) In\u00a0[\u00a0]: Copied!
prompt_input = '\u00bfque hora es?'\n
prompt_input = '\u00bfque hora es?' In\u00a0[\u00a0]: Copied!
llm_response = chain(prompt_input)\n\ndisplay(llm_response)\n
llm_response = chain(prompt_input) display(llm_response) In\u00a0[\u00a0]: Copied!
# Initialize Huggingface-based feedback function collection class:\nhugs = Huggingface()\n\n# Define a language match feedback function using HuggingFace.\nf_lang_match = Feedback(hugs.language_match).on_input_output()\n# By default this will check language match on the main app input and main app\n# output.\n
# Initialize Huggingface-based feedback function collection class: hugs = Huggingface() # Define a language match feedback function using HuggingFace. f_lang_match = Feedback(hugs.language_match).on_input_output() # By default this will check language match on the main app input and main app # output. In\u00a0[\u00a0]: Copied!
tru_recorder = TruChain(chain,\n app_id='Chain1_ChatApplication',\n feedbacks=[f_lang_match])\n
tru_recorder = TruChain(chain, app_id='Chain1_ChatApplication', feedbacks=[f_lang_match]) In\u00a0[\u00a0]: Copied!
with tru_recorder as recording:\n llm_response = chain(prompt_input)\n\ndisplay(llm_response)\n
with tru_recorder as recording: llm_response = chain(prompt_input) display(llm_response) In\u00a0[\u00a0]: Copied!
# The record of the ap invocation can be retrieved from the `recording`:\n\nrec = recording.get() # use .get if only one record\n# recs = recording.records # use .records if multiple\n\ndisplay(rec)\n
# The record of the ap invocation can be retrieved from the `recording`: rec = recording.get() # use .get if only one record # recs = recording.records # use .records if multiple display(rec) In\u00a0[\u00a0]: Copied!
# The results of the feedback functions can be rertireved from the record. These\n# are `Future` instances (see `concurrent.futures`). You can use `as_completed`\n# to wait until they have finished evaluating.\n\nfrom concurrent.futures import as_completed\n\nfor feedback_future in as_completed(rec.feedback_results):\n feedback, feedback_result = feedback_future.result()\n \n feedback: Feedback\n feedbac_result: FeedbackResult\n\n display(feedback.name, feedback_result.result)\n
# The results of the feedback functions can be rertireved from the record. These # are `Future` instances (see `concurrent.futures`). You can use `as_completed` # to wait until they have finished evaluating. from concurrent.futures import as_completed for feedback_future in as_completed(rec.feedback_results): feedback, feedback_result = feedback_future.result() feedback: Feedback feedbac_result: FeedbackResult display(feedback.name, feedback_result.result) In\u00a0[\u00a0]: Copied!
tru.run_dashboard() # open a local streamlit app to explore\n\n# tru.stop_dashboard() # stop if needed\n
tru.run_dashboard() # open a local streamlit app to explore # tru.stop_dashboard() # stop if needed
Alternatively, you can run trulens-eval from a command line in the same folder to start the dashboard.
Note: Feedback functions evaluated in the deferred manner can be seen in the \"Progress\" page of the TruLens dashboard.
In\u00a0[\u00a0]: Copied!
tru.get_records_and_feedback(app_ids=[])[0] # pass an empty list of app_ids to get all\n
tru.get_records_and_feedback(app_ids=[])[0] # pass an empty list of app_ids to get all"},{"location":"trulens_eval/langchain_quickstart/#langchain-quickstart","title":"Langchain Quickstart\u00b6","text":"
In this quickstart you will create a simple LLM Chain and learn how to log it and get feedback on an LLM response.
"},{"location":"trulens_eval/langchain_quickstart/#setup","title":"Setup\u00b6","text":""},{"location":"trulens_eval/langchain_quickstart/#add-api-keys","title":"Add API keys\u00b6","text":"
For this quickstart you will need Open AI and Huggingface keys
"},{"location":"trulens_eval/langchain_quickstart/#import-from-langchain-and-trulens","title":"Import from LangChain and TruLens\u00b6","text":""},{"location":"trulens_eval/langchain_quickstart/#create-simple-llm-application","title":"Create Simple LLM Application\u00b6","text":"
This example uses a LangChain framework and OpenAI LLM
"},{"location":"trulens_eval/langchain_quickstart/#send-your-first-request","title":"Send your first request\u00b6","text":""},{"location":"trulens_eval/langchain_quickstart/#initialize-feedback-functions","title":"Initialize Feedback Function(s)\u00b6","text":""},{"location":"trulens_eval/langchain_quickstart/#instrument-chain-for-logging-with-trulens","title":"Instrument chain for logging with TruLens\u00b6","text":""},{"location":"trulens_eval/langchain_quickstart/#retrieve-records-and-feedback","title":"Retrieve records and feedback\u00b6","text":""},{"location":"trulens_eval/langchain_quickstart/#explore-in-a-dashboard","title":"Explore in a Dashboard\u00b6","text":""},{"location":"trulens_eval/langchain_quickstart/#chain-leaderboard","title":"Chain Leaderboard\u00b6","text":"
Understand how your LLM application is performing at a glance. Once you've set up logging and evaluation in your application, you can view key performance statistics including cost and average feedback value across all of your LLM apps using the chain leaderboard. As you iterate new versions of your LLM application, you can compare their performance across all of the different quality metrics you've set up.
Note: Average feedback values are returned and displayed in a range from 0 (worst) to 1 (best).
To dive deeper on a particular chain, click \"Select Chain\".
"},{"location":"trulens_eval/langchain_quickstart/#understand-chain-performance-with-evaluations","title":"Understand chain performance with Evaluations\u00b6","text":"
To learn more about the performance of a particular chain or LLM model, we can select it to view its evaluations at the record level. LLM quality is assessed through the use of feedback functions. Feedback functions are extensible methods for determining the quality of LLM responses and can be applied to any downstream LLM task. Out of the box we provide a number of feedback functions for assessing model agreement, sentiment, relevance and more.
The evaluations tab provides record-level metadata and feedback on the quality of your LLM application.
"},{"location":"trulens_eval/langchain_quickstart/#deep-dive-into-full-chain-metadata","title":"Deep dive into full chain metadata\u00b6","text":"
Click on a record to dive deep into all of the details of your chain stack and underlying LLM, captured by tru_chain_recorder.
If you prefer the raw format, you can quickly get it using the \"Display full chain json\" or \"Display full record json\" buttons at the bottom of the page.
"},{"location":"trulens_eval/langchain_quickstart/#or-view-results-directly-in-your-notebook","title":"Or view results directly in your notebook\u00b6","text":""},{"location":"trulens_eval/llama_index_instrumentation/","title":"Llama-Index Integration","text":"In\u00a0[\u00a0]: Copied!
from llama_index import VectorStoreIndex, SimpleWebPageReader\nfrom trulens_eval import TruLlama\n\ndocuments = SimpleWebPageReader(html_to_text=True).load_data(\n [\"http://paulgraham.com/worked.html\"]\n)\nindex = VectorStoreIndex.from_documents(documents)\n\nquery_engine = index.as_query_engine()\n
from llama_index import VectorStoreIndex, SimpleWebPageReader from trulens_eval import TruLlama documents = SimpleWebPageReader(html_to_text=True).load_data( [\"http://paulgraham.com/worked.html\"] ) index = VectorStoreIndex.from_documents(documents) query_engine = index.as_query_engine()
To instrument an Llama-Index query engine, all that's required is to wrap it using TruLlama.
In\u00a0[\u00a0]: Copied!
tru_query_engine_recorder = TruLlama(query_engine)\n\nwith tru_query_engine_recorder as recording:\n llm_response = query_engine.query(\"What did the author do growing up?\")\n
tru_query_engine_recorder = TruLlama(query_engine) with tru_query_engine_recorder as recording: llm_response = query_engine.query(\"What did the author do growing up?\")
You can find the full quickstart available here: Llama-Index Quickstart
In\u00a0[\u00a0]: Copied!
# Imports main tools:\nfrom trulens_eval import TruLlama, Feedback, Tru, feedback, Select\ntru = Tru()\n\nfrom llama_index import VectorStoreIndex, SimpleWebPageReader\n\ndocuments = SimpleWebPageReader(html_to_text=True).load_data(\n [\"http://paulgraham.com/worked.html\"]\n)\nindex = VectorStoreIndex.from_documents(documents)\n\nchat_engine = index.as_chat_engine(streaming=True)\n
# Imports main tools: from trulens_eval import TruLlama, Feedback, Tru, feedback, Select tru = Tru() from llama_index import VectorStoreIndex, SimpleWebPageReader documents = SimpleWebPageReader(html_to_text=True).load_data( [\"http://paulgraham.com/worked.html\"] ) index = VectorStoreIndex.from_documents(documents) chat_engine = index.as_chat_engine(streaming=True)
To instrument an Llama-Index achat engine, all that's required is to wrap it using TruLlama - just like with the query engine.
In\u00a0[\u00a0]: Copied!
tru_chat_recorder = TruLlama(chat_engine)\n\nwith tru_chat_recorder as recording:\n llm_response_async = await chat_engine.aquery(\"What did the author do growing up?\")\n\nprint(llm_response_async)\n
tru_chat_recorder = TruLlama(chat_engine) with tru_chat_recorder as recording: llm_response_async = await chat_engine.aquery(\"What did the author do growing up?\") print(llm_response_async) In\u00a0[\u00a0]: Copied!
from llama_index import VectorStoreIndex, SimpleWebPageReader\nfrom trulens_eval import TruLlama\n\ndocuments = SimpleWebPageReader(html_to_text=True).load_data(\n [\"http://paulgraham.com/worked.html\"]\n)\nindex = VectorStoreIndex.from_documents(documents)\n\nquery_engine = index.as_query_engine(streaming=True)\n
from llama_index import VectorStoreIndex, SimpleWebPageReader from trulens_eval import TruLlama documents = SimpleWebPageReader(html_to_text=True).load_data( [\"http://paulgraham.com/worked.html\"] ) index = VectorStoreIndex.from_documents(documents) query_engine = index.as_query_engine(streaming=True)
Just like with other methods, just wrap your streaming query engine with TruLlama and operate like before.
You can also print the response tokens as they are generated using the response_gen attribute.
In\u00a0[\u00a0]: Copied!
tru_query_engine_recorder = TruLlama(query_engine)\n\nwith tru_query_engine_recorder as recording:\n response = query_engine.query(\"What did the author do growing up?\")\n\nfor c in response.response_gen:\n print(c)\n
tru_query_engine_recorder = TruLlama(query_engine) with tru_query_engine_recorder as recording: response = query_engine.query(\"What did the author do growing up?\") for c in response.response_gen: print(c)
For more usage examples, check out the Llama-Index examples directory.
"},{"location":"trulens_eval/llama_index_instrumentation/#llama-index-integration","title":"Llama-Index Integration\u00b6","text":"
TruLens provides TruLlama, a deep integration with Llama-Index to allow you to inspect and evaluate the internals of your application built using Llama-Index.
TruLlama captures all of the metrics and metadata listed in the instrumentation overview. In addition, TruLlama provides the select_source_nodes method to capture the source nodes of your query.
"},{"location":"trulens_eval/llama_index_instrumentation/#supported-methods","title":"Supported methods\u00b6","text":"
TruLlama supports both sync and async modes using the following Llama-Index query engine methods:
queryaquerychatachatstream_chatastream_chat
"},{"location":"trulens_eval/llama_index_instrumentation/#example-usage","title":"Example usage\u00b6","text":"
Below is a quick example of usage. First, we'll create a standard Llama-Index query engine from Paul Graham's Essay, What I Worked On
"},{"location":"trulens_eval/llama_index_instrumentation/#async-support","title":"Async Support\u00b6","text":"
TruLlama also provides async support for Llama-Index through the aquery, achat, and astream_chat methods. This allows you to track and evaluate async applciations.
As an example, below is an Llama-Index async chat engine (achat).
"},{"location":"trulens_eval/llama_index_instrumentation/#streaming-support","title":"Streaming Support\u00b6","text":"
TruLlama also provides streaming support for Llama-Index. This allows you to track and evaluate streaming applications.
As an example, below is an Llama-Index query engine with streaming.
"},{"location":"trulens_eval/llama_index_quickstart/","title":"Llama-Index Quickstart","text":"In\u00a0[\u00a0]: Copied!
# pip install trulens-eval==0.18.0 llama_index>=0.8.69 html2text>=2020.1.16\n
# pip install trulens-eval==0.18.0 llama_index>=0.8.69 html2text>=2020.1.16 In\u00a0[\u00a0]: Copied!
import os\nos.environ[\"OPENAI_API_KEY\"] = \"...\"\n
import os os.environ[\"OPENAI_API_KEY\"] = \"...\" In\u00a0[\u00a0]: Copied!
from trulens_eval import Feedback, Tru, TruLlama\nfrom trulens_eval.feedback import Groundedness\nfrom trulens_eval.feedback.provider.openai import OpenAI\n\ntru = Tru()\n
from trulens_eval import Feedback, Tru, TruLlama from trulens_eval.feedback import Groundedness from trulens_eval.feedback.provider.openai import OpenAI tru = Tru() In\u00a0[\u00a0]: Copied!
from llama_index import VectorStoreIndex\nfrom llama_index.readers.web import SimpleWebPageReader\n\ndocuments = SimpleWebPageReader(\n html_to_text=True\n).load_data([\"http://paulgraham.com/worked.html\"])\nindex = VectorStoreIndex.from_documents(documents)\n\nquery_engine = index.as_query_engine()\n
from llama_index import VectorStoreIndex from llama_index.readers.web import SimpleWebPageReader documents = SimpleWebPageReader( html_to_text=True ).load_data([\"http://paulgraham.com/worked.html\"]) index = VectorStoreIndex.from_documents(documents) query_engine = index.as_query_engine() In\u00a0[\u00a0]: Copied!
response = query_engine.query(\"What did the author do growing up?\")\nprint(response)\n
response = query_engine.query(\"What did the author do growing up?\") print(response) In\u00a0[\u00a0]: Copied!
import numpy as np\n\n# Initialize provider class\nopenai = OpenAI()\n\ngrounded = Groundedness(groundedness_provider=OpenAI())\n\n# Define a groundedness feedback function\nf_groundedness = Feedback(grounded.groundedness_measure_with_cot_reasons).on(\n TruLlama.select_source_nodes().node.text\n ).on_output(\n ).aggregate(grounded.grounded_statements_aggregator)\n\n# Question/answer relevance between overall question and answer.\nf_qa_relevance = Feedback(openai.relevance).on_input_output()\n\n# Question/statement relevance between question and each context chunk.\nf_qs_relevance = Feedback(openai.qs_relevance).on_input().on(\n TruLlama.select_source_nodes().node.text\n ).aggregate(np.mean)\n
import numpy as np # Initialize provider class openai = OpenAI() grounded = Groundedness(groundedness_provider=OpenAI()) # Define a groundedness feedback function f_groundedness = Feedback(grounded.groundedness_measure_with_cot_reasons).on( TruLlama.select_source_nodes().node.text ).on_output( ).aggregate(grounded.grounded_statements_aggregator) # Question/answer relevance between overall question and answer. f_qa_relevance = Feedback(openai.relevance).on_input_output() # Question/statement relevance between question and each context chunk. f_qs_relevance = Feedback(openai.qs_relevance).on_input().on( TruLlama.select_source_nodes().node.text ).aggregate(np.mean) In\u00a0[\u00a0]: Copied!
tru_query_engine_recorder = TruLlama(query_engine,\n app_id='LlamaIndex_App1',\n feedbacks=[f_groundedness, f_qa_relevance, f_qs_relevance])\n
tru_query_engine_recorder = TruLlama(query_engine, app_id='LlamaIndex_App1', feedbacks=[f_groundedness, f_qa_relevance, f_qs_relevance]) In\u00a0[\u00a0]: Copied!
# or as context manager\nwith tru_query_engine_recorder as recording:\n query_engine.query(\"What did the author do growing up?\")\n
# or as context manager with tru_query_engine_recorder as recording: query_engine.query(\"What did the author do growing up?\") In\u00a0[\u00a0]: Copied!
tru.run_dashboard() # open a local streamlit app to explore\n\n# tru.stop_dashboard() # stop if needed\n
tru.run_dashboard() # open a local streamlit app to explore # tru.stop_dashboard() # stop if needed
Alternatively, you can run trulens-eval from a command line in the same folder to start the dashboard.
Note: Feedback functions evaluated in the deferred manner can be seen in the \"Progress\" page of the TruLens dashboard.
In\u00a0[\u00a0]: Copied!
tru.get_records_and_feedback(app_ids=[])[0] # pass an empty list of app_ids to get all\n
tru.get_records_and_feedback(app_ids=[])[0] # pass an empty list of app_ids to get all"},{"location":"trulens_eval/llama_index_quickstart/#llama-index-quickstart","title":"Llama-Index Quickstart\u00b6","text":"
In this quickstart you will create a simple Llama Index App and learn how to log it and get feedback on an LLM response.
For evaluation, we will leverage the \"hallucination triad\" of groundedness, context relevance and answer relevance.
"},{"location":"trulens_eval/llama_index_quickstart/#setup","title":"Setup\u00b6","text":""},{"location":"trulens_eval/llama_index_quickstart/#install-dependencies","title":"Install dependencies\u00b6","text":"
Let's install some of the dependencies for this notebook if we don't have them already
"},{"location":"trulens_eval/llama_index_quickstart/#add-api-keys","title":"Add API keys\u00b6","text":"
For this quickstart, you will need Open AI and Huggingface keys. The OpenAI key is used for embeddings and GPT, and the Huggingface key is used for evaluation.
"},{"location":"trulens_eval/llama_index_quickstart/#import-from-llamaindex-and-trulens","title":"Import from LlamaIndex and TruLens\u00b6","text":""},{"location":"trulens_eval/llama_index_quickstart/#create-simple-llm-application","title":"Create Simple LLM Application\u00b6","text":"
This example uses LlamaIndex which internally uses an OpenAI LLM.
"},{"location":"trulens_eval/llama_index_quickstart/#send-your-first-request","title":"Send your first request\u00b6","text":""},{"location":"trulens_eval/llama_index_quickstart/#initialize-feedback-functions","title":"Initialize Feedback Function(s)\u00b6","text":""},{"location":"trulens_eval/llama_index_quickstart/#instrument-app-for-logging-with-trulens","title":"Instrument app for logging with TruLens\u00b6","text":""},{"location":"trulens_eval/llama_index_quickstart/#explore-in-a-dashboard","title":"Explore in a Dashboard\u00b6","text":""},{"location":"trulens_eval/llama_index_quickstart/#or-view-results-directly-in-your-notebook","title":"Or view results directly in your notebook\u00b6","text":""},{"location":"trulens_eval/logging/","title":"Logging Methods","text":"In\u00a0[\u00a0]: Copied!
truchain = TruChain(\n chain,\n app_id='Chain1_ChatApplication',\n tru=tru\n)\ntruchain(\"This will be automatically logged.\")\n
truchain = TruChain( chain, app_id='Chain1_ChatApplication', tru=tru ) truchain(\"This will be automatically logged.\")
Feedback functions can also be logged automatically by providing them in a list to the feedbacks arg.
In\u00a0[\u00a0]: Copied!
truchain = TruChain(\n chain,\n app_id='Chain1_ChatApplication',\n feedbacks=[f_lang_match], # feedback functions\n tru=tru\n)\ntruchain(\"This will be automatically logged.\")\n
truchain = TruChain( chain, app_id='Chain1_ChatApplication', feedbacks=[f_lang_match], # feedback functions tru=tru ) truchain(\"This will be automatically logged.\") In\u00a0[\u00a0]: Copied!
tc = TruChain(chain, app_id='Chain1_ChatApplication')\n
tc = TruChain(chain, app_id='Chain1_ChatApplication') In\u00a0[\u00a0]: Copied!
prompt_input = 'que hora es?'\ngpt3_response, record = tc.call_with_record(prompt_input)\n
prompt_input = 'que hora es?' gpt3_response, record = tc.call_with_record(prompt_input)
We can log the records but first we need to log the chain itself.
In\u00a0[\u00a0]: Copied!
tru.add_app(app=truchain)\n
tru.add_app(app=truchain)
Then we can log the record:
In\u00a0[\u00a0]: Copied!
tru.add_record(record)\n
tru.add_record(record) In\u00a0[\u00a0]: Copied!
thumb_result = True\ntru.add_feedback(name=\"\ud83d\udc4d (1) or \ud83d\udc4e (0)\", \n record_id=record.record_id, \n result=thumb_result)\n
thumb_result = True tru.add_feedback(name=\"\ud83d\udc4d (1) or \ud83d\udc4e (0)\", record_id=record.record_id, result=thumb_result) In\u00a0[\u00a0]: Copied!
feedback_results = tru.run_feedback_functions(\n record=record,\n feedback_functions=[f_lang_match]\n)\ndisplay(feedback_results)\n
feedback_results = tru.run_feedback_functions( record=record, feedback_functions=[f_lang_match] ) display(feedback_results)
After capturing feedback, you can then log it to your local database.
In\u00a0[\u00a0]: Copied!
tru.add_feedbacks(feedback_results)\n
tru.add_feedbacks(feedback_results) In\u00a0[\u00a0]: Copied!
truchain: TruChain = TruChain(\n chain,\n app_id='Chain1_ChatApplication',\n feedbacks=[f_lang_match],\n tru=tru,\n feedback_mode=\"deferred\"\n)\n\ntru.start_evaluator()\ntruchain(\"This will be logged by deferred evaluator.\")\ntru.stop_evaluator()\n
truchain: TruChain = TruChain( chain, app_id='Chain1_ChatApplication', feedbacks=[f_lang_match], tru=tru, feedback_mode=\"deferred\" ) tru.start_evaluator() truchain(\"This will be logged by deferred evaluator.\") tru.stop_evaluator()"},{"location":"trulens_eval/logging/#logging-methods","title":"Logging Methods\u00b6","text":""},{"location":"trulens_eval/logging/#automatic-logging","title":"Automatic Logging\u00b6","text":"
The simplest method for logging with TruLens is by wrapping with TruChain and including the tru argument, as shown in the quickstart.
This is done like so:
"},{"location":"trulens_eval/logging/#manual-logging","title":"Manual Logging\u00b6","text":""},{"location":"trulens_eval/logging/#wrap-with-truchain-to-instrument-your-chain","title":"Wrap with TruChain to instrument your chain\u00b6","text":""},{"location":"trulens_eval/logging/#set-up-logging-and-instrumentation","title":"Set up logging and instrumentation\u00b6","text":"
Making the first call to your wrapped LLM Application will now also produce a log or \"record\" of the chain execution.
"},{"location":"trulens_eval/logging/#log-app-feedback","title":"Log App Feedback\u00b6","text":"
Capturing app feedback such as user feedback of the responses can be added with one call.
"},{"location":"trulens_eval/logging/#evaluate-quality","title":"Evaluate Quality\u00b6","text":"
Following the request to your app, you can then evaluate LLM quality using feedback functions. This is completed in a sequential call to minimize latency for your application, and evaluations will also be logged to your local machine.
To get feedback on the quality of your LLM, you can use any of the provided feedback functions or add your own.
To assess your LLM quality, you can provide the feedback functions to tru.run_feedback() in a list provided to feedback_functions.
"},{"location":"trulens_eval/logging/#out-of-band-feedback-evaluation","title":"Out-of-band Feedback evaluation\u00b6","text":"
In the above example, the feedback function evaluation is done in the same process as the chain evaluation. The alternative approach is the use the provided persistent evaluator started via tru.start_deferred_feedback_evaluator. Then specify the feedback_mode for TruChain as deferred to let the evaluator handle the feedback functions.
For demonstration purposes, we start the evaluator here but it can be started in another process.
"},{"location":"trulens_eval/text2text_quickstart/","title":"Text to Text Quickstart","text":"In\u00a0[\u00a0]: Copied!
# ! pip install trulens_eval==0.17.0 openai==1.1.1\n
# ! pip install trulens_eval==0.17.0 openai==1.1.1 In\u00a0[\u00a0]: Copied!
import logging\n
import logging In\u00a0[\u00a0]: Copied!
import os\nos.environ[\"OPENAI_API_KEY\"] = \"...\"\n
import os os.environ[\"OPENAI_API_KEY\"] = \"...\" In\u00a0[\u00a0]: Copied!
from openai import OpenAI\n\nclient = OpenAI()\n
from openai import OpenAI client = OpenAI() In\u00a0[\u00a0]: Copied!
from IPython.display import JSON\n\n# Imports main tools:\nfrom trulens_eval import Feedback, OpenAI as fOpenAI, Tru\ntru = Tru()\ntru.reset_database()\n
from IPython.display import JSON # Imports main tools: from trulens_eval import Feedback, OpenAI as fOpenAI, Tru tru = Tru() tru.reset_database() In\u00a0[\u00a0]: Copied!
def llm_standalone(prompt):\n return client.chat.completions.create(\n model=\"gpt-3.5-turbo\",\n messages=[\n {\"role\": \"system\", \"content\": \"You are a question and answer bot, and you answer super upbeat.\"},\n {\"role\": \"user\", \"content\": prompt}\n ]\n ).choices[0].message.content\n def llm_standalone(prompt): return client.chat.completions.create( model=\"gpt-3.5-turbo\", messages=[ {\"role\": \"system\", \"content\": \"You are a question and answer bot, and you answer super upbeat.\"}, {\"role\": \"user\", \"content\": prompt} ] ).choices[0].message.content In\u00a0[\u00a0]: Copied!
prompt_input=\"How good is language AI?\"\nprompt_output = llm_standalone(prompt_input)\nprompt_output\n
prompt_input=\"How good is language AI?\" prompt_output = llm_standalone(prompt_input) prompt_output In\u00a0[\u00a0]: Copied!
# Initialize OpenAI-based feedback function collection class:\nfopenai = fOpenAI()\n\n# Define a relevance function from openai\nf_relevance = Feedback(fopenai.relevance).on_input_output()\n
# Initialize OpenAI-based feedback function collection class: fopenai = fOpenAI() # Define a relevance function from openai f_relevance = Feedback(fopenai.relevance).on_input_output() In\u00a0[\u00a0]: Copied!
from trulens_eval import TruBasicApp\ntru_llm_standalone_recorder = TruBasicApp(llm_standalone, app_id=\"Happy Bot\", feedbacks=[f_relevance])\n
from trulens_eval import TruBasicApp tru_llm_standalone_recorder = TruBasicApp(llm_standalone, app_id=\"Happy Bot\", feedbacks=[f_relevance]) In\u00a0[\u00a0]: Copied!
with tru_llm_standalone_recorder as recording:\n tru_llm_standalone_recorder.app(prompt_input)\n
with tru_llm_standalone_recorder as recording: tru_llm_standalone_recorder.app(prompt_input) In\u00a0[\u00a0]: Copied!
tru.run_dashboard() # open a local streamlit app to explore\n\n# tru.stop_dashboard() # stop if needed\n
tru.run_dashboard() # open a local streamlit app to explore # tru.stop_dashboard() # stop if needed
Alternatively, you can run trulens-eval from a command line in the same folder to start the dashboard.
In\u00a0[\u00a0]: Copied!
tru.get_records_and_feedback(app_ids=[])[0] # pass an empty list of app_ids to get all\n
tru.get_records_and_feedback(app_ids=[])[0] # pass an empty list of app_ids to get all"},{"location":"trulens_eval/text2text_quickstart/#text-to-text-quickstart","title":"Text to Text Quickstart\u00b6","text":"
In this quickstart you will create a simple text to text application and learn how to log it and get feedback.
"},{"location":"trulens_eval/text2text_quickstart/#setup","title":"Setup\u00b6","text":""},{"location":"trulens_eval/text2text_quickstart/#add-api-keys","title":"Add API keys\u00b6","text":"
For this quickstart you will need Open AI and Huggingface keys
"},{"location":"trulens_eval/text2text_quickstart/#import-from-trulens","title":"Import from TruLens\u00b6","text":""},{"location":"trulens_eval/text2text_quickstart/#create-simple-text-to-text-application","title":"Create Simple Text to Text Application\u00b6","text":"
This example uses a bare bones OpenAI LLM, and a non-LLM just for demonstration purposes.
"},{"location":"trulens_eval/text2text_quickstart/#send-your-first-request","title":"Send your first request\u00b6","text":""},{"location":"trulens_eval/text2text_quickstart/#initialize-feedback-functions","title":"Initialize Feedback Function(s)\u00b6","text":""},{"location":"trulens_eval/text2text_quickstart/#instrument-the-callable-for-logging-with-trulens","title":"Instrument the callable for logging with TruLens\u00b6","text":""},{"location":"trulens_eval/text2text_quickstart/#explore-in-a-dashboard","title":"Explore in a Dashboard\u00b6","text":""},{"location":"trulens_eval/text2text_quickstart/#or-view-results-directly-in-your-notebook","title":"Or view results directly in your notebook\u00b6","text":""},{"location":"trulens_eval/use_cases_agent/","title":"TruLens for LLM Agents","text":"
This section highlights different end-to-end use cases that TruLens can help with when building LLM agent applications. For each use case, we not only motivate the use case but also discuss which components are most helpful for solving that use case.
Validate LLM Agent Actions
Verify that your agent uses the intended tools and check it against business requirements.
Detect LLM Agent Tool Gaps/Drift
Identify when your LLM agent is missing the tools it needs to complete the tasks required.
"},{"location":"trulens_eval/use_cases_any/","title":"TruLens for any application","text":"
This section highlights different end-to-end use cases that TruLens can help with for any LLM application. For each use case, we not only motivate the use case but also discuss which components are most helpful for solving that use case.
Model Selection
Use TruLens to choose the most performant and efficient model for your application.
Moderation and Safety
Monitor your LLM application responses against a set of moderation and safety checks.
Language Verification
Verify your LLM application responds in the same language it is prompted.
PII Detection
Detect PII in prompts or LLM response to prevent unintended leaks.
"},{"location":"trulens_eval/use_cases_production/","title":"Moving apps from dev to prod","text":"
This section highlights different end-to-end use cases that TruLens can help with. For each use case, we not only motivate the use case but also discuss which components are most helpful for solving that use case.
Async Evaluation
Evaluate your applications that leverage async mode.
Deferred Evaluation
Defer evaluations to off-peak times.
Using AzureOpenAI
Use AzureOpenAI to run feedback functions.
Using AWS Bedrock
Use AWS Bedrock to run feedback functions.
"},{"location":"trulens_eval/use_cases_rag/","title":"For Retrieval Augmented Generation (RAG)","text":"
This section highlights different end-to-end use cases that TruLens can help with when building RAG applications. For each use case, we not only motivate the use case but also discuss which components are most helpful for solving that use case.
Detect and Mitigate Hallucination
Use groundedness feedback to ensure that your LLM responds using only the information retrieved from a verified knowledge source.
Improve Retrieval Quality
Measure and identify ways to improve the quality of retrieval for your RAG.
Optimize App Configuration
Iterate through a set of configuration options for your RAG including different metrics, parameters, models and more; find the most performant with TruLens.
Verify the Summarization Quality
Ensure that LLM summarizations contain the key points from source documents.
"},{"location":"trulens_eval/where_to_log/","title":"Where to Log","text":"
By default, all data is logged to the current working directory to default.sqlite (sqlite:///default.sqlite). Data can be logged to a SQLAlchemy-compatible referred to by database_url in the format dialect+driver://username:password@host:port/database.
See this article for more details on SQLAlchemy database URLs.
For example, for Postgres database trulens running on localhost with username trulensuser and password password set up a connection like so.
from trulens_eval import Tru\ntru = Tru(database_url=\"postgresql://trulensuser:password@localhost/trulens\")\n
After which you should receive the following message:
\ud83e\udd91 Tru initialized with db url postgresql://trulensuser:password@localhost/trulens.\n
"},{"location":"trulens_eval/api/appdefinition/","title":"App Definition","text":"
Bases: SerialModel, WithClassInfo
Source code in
trulens_eval/trulens_eval/schema.py class AppDefinition(SerialModel, WithClassInfo):\n # Serialized fields here whereas app.py:App contains\n # non-serialized fields.\n\n class Config:\n arbitrary_types_allowed = True\n\n app_id: AppID\n tags: Tags\n metadata: Metadata # TODO: rename to meta for consistency with other metas\n\n # Feedback functions to evaluate on each record. Unlike the above, these are\n # meant to be serialized.\n feedback_definitions: Sequence[FeedbackDefinition] = []\n\n # NOTE: Custom feedback functions cannot be run deferred and will be run as\n # if \"withappthread\" was set.\n feedback_mode: FeedbackMode = FeedbackMode.WITH_APP_THREAD\n\n # Class of the main instrumented object.\n root_class: Class # TODO: make classvar\n\n # App's main method. To be filled in by subclass. Want to make this abstract\n # but this causes problems when trying to load an AppDefinition from json.\n root_callable: ClassVar[FunctionOrMethod]\n\n # Wrapped app in jsonized form.\n app: JSON\n\n # EXPERIMENTAL\n # NOTE: temporary unsafe serialization of function that loads the app:\n # Dump of the initial app before any invocations. Can be used to create a new session.\n initial_app_loader_dump: Optional[SerialBytes] = None\n\n # Info to store about the app and to display in dashboard. This is useful if\n # app itself cannot be serialized. `app_extra_json`, then, can stand in place for\n # whatever the user might want to see about the app.\n app_extra_json: JSON\n\n @staticmethod\n def continue_session(\n app_definition_json: JSON, app: Any\n ) -> 'AppDefinition':\n # initial_app_loader: Optional[Callable] = None) -> 'AppDefinition':\n\"\"\"\n Create a copy of the json serialized app with the enclosed app being\n initialized to its initial state before any records are produced (i.e.\n blank memory).\n \"\"\"\n\n app_definition_json['app'] = app\n\n cls = WithClassInfo.get_class(app_definition_json)\n\n return cls(**app_definition_json)\n\n @staticmethod\n def new_session(\n app_definition_json: JSON,\n initial_app_loader: Optional[Callable] = None\n ) -> 'AppDefinition':\n\"\"\"\n Create a copy of the json serialized app with the enclosed app being\n initialized to its initial state before any records are produced (i.e.\n blank memory).\n \"\"\"\n\n serial_bytes_json: Optional[JSON] = app_definition_json[\n 'initial_app_loader_dump']\n\n if initial_app_loader is None:\n assert serial_bytes_json is not None, \"Cannot create new session without `initial_app_loader`.\"\n\n serial_bytes = SerialBytes.parse_obj(serial_bytes_json)\n\n app = dill.loads(serial_bytes.data)()\n\n else:\n app = initial_app_loader()\n data = dill.dumps(initial_app_loader, recurse=True)\n serial_bytes = SerialBytes(data=data)\n serial_bytes_json = serial_bytes.dict()\n\n app_definition_json['app'] = app\n app_definition_json['initial_app_loader_dump'] = serial_bytes_json\n\n cls: Type[App] = WithClassInfo.get_class(app_definition_json)\n\n return cls.parse_obj(app_definition_json)\n\n def jsonify_extra(self, content):\n # Called by jsonify for us to add any data we might want to add to the\n # serialization of `app`.\n if self.app_extra_json is not None:\n content['app'].update(self.app_extra_json)\n\n return content\n\n def __init__(\n self,\n app_id: Optional[AppID] = None,\n tags: Optional[Tags] = None,\n metadata: Optional[Metadata] = None,\n feedback_mode: FeedbackMode = FeedbackMode.WITH_APP_THREAD,\n app_extra_json: JSON = None,\n **kwargs\n ):\n\n # for us:\n kwargs['app_id'] = \"temporary\" # will be adjusted below\n kwargs['feedback_mode'] = feedback_mode\n kwargs['tags'] = \"\"\n kwargs['metadata'] = {}\n kwargs['app_extra_json'] = app_extra_json or dict()\n\n # for WithClassInfo:\n kwargs['obj'] = self\n\n super().__init__(**kwargs)\n\n if app_id is None:\n app_id = obj_id_of_obj(obj=self.dict(), prefix=\"app\")\n\n self.app_id = app_id\n\n if tags is None:\n tags = \"-\" # Set tags to a \"-\" if None is provided\n self.tags = tags\n\n if metadata is None:\n metadata = {}\n self.metadata = metadata\n\n # EXPERIMENTAL\n if 'initial_app_loader' in kwargs:\n try:\n dump = dill.dumps(kwargs['initial_app_loader'], recurse=True)\n\n if len(dump) > MAX_DILL_SIZE:\n logger.warning(\n f\"`initial_app_loader` dump is too big ({humanize.naturalsize(len(dump))} > {humanize.naturaldate(MAX_DILL_SIZE)} bytes). \"\n \"If you are loading large objects, include the loading logic inside `initial_app_loader`.\"\n )\n else:\n self.initial_app_loader_dump = SerialBytes(data=dump)\n\n # This is an older serialization approach that saved things\n # in local files instead of the DB. Leaving here for now as\n # serialization of large apps might make this necessary\n # again.\n\"\"\"\n path_json = Path.cwd() / f\"{app_id}.json\"\n path_dill = Path.cwd() / f\"{app_id}.dill\"\n\n with path_json.open(\"w\") as fh:\n fh.write(json_str_of_obj(self))\n\n with path_dill.open(\"wb\") as fh:\n fh.write(dump)\n\n print(f\"Wrote loadable app to {path_json} and {path_dill}.\")\n \"\"\"\n\n except Exception as e:\n logger.warning(\n f\"Could not serialize app loader. \"\n f\"Some trulens features may not be available: {e}\"\n )\n\n @staticmethod\n def get_loadable_apps():\n # EXPERIMENTAL\n\"\"\"\n Gets a list of all of the loadable apps. This is those that have\n `initial_app_loader_dump` set.\n \"\"\"\n\n rets = []\n\n from trulens_eval import Tru\n\n tru = Tru()\n\n apps = tru.get_apps()\n for app in apps:\n dump = app['initial_app_loader_dump']\n if dump is not None:\n rets.append(app)\n\n return rets\n\n def dict(self):\n # Unsure if the check below is needed. Sometimes we have an `app.App`` but\n # it is considered an `AppDefinition` and is thus using this definition\n # of `dict` instead of the one in `app.App`.\n\n from trulens_eval.trulens_eval import app\n if isinstance(self, app.App):\n return jsonify(self, instrument=self.instrument)\n else:\n return jsonify(self)\n\n @classmethod\n def select_inputs(cls) -> JSONPath:\n\"\"\"\n Get the path to the main app's call inputs.\n \"\"\"\n\n return getattr(\n Select.RecordCalls,\n cls.root_callable.default_factory().name\n ).args\n\n @classmethod\n def select_outputs(cls) -> JSONPath:\n\"\"\"\n Get the path to the main app's call outputs.\n \"\"\"\n\n return getattr(\n Select.RecordCalls,\n cls.root_callable.default_factory().name\n ).rets\n
"},{"location":"trulens_eval/api/appdefinition/#trulens_eval.trulens_eval.schema.AppDefinition.continue_session","title":"
continue_session(app_definition_json, app) staticmethod","text":"
Create a copy of the json serialized app with the enclosed app being initialized to its initial state before any records are produced (i.e. blank memory).
Source code in
trulens_eval/trulens_eval/schema.py @staticmethod\ndef continue_session(\n app_definition_json: JSON, app: Any\n) -> 'AppDefinition':\n # initial_app_loader: Optional[Callable] = None) -> 'AppDefinition':\n\"\"\"\n Create a copy of the json serialized app with the enclosed app being\n initialized to its initial state before any records are produced (i.e.\n blank memory).\n \"\"\"\n\n app_definition_json['app'] = app\n\n cls = WithClassInfo.get_class(app_definition_json)\n\n return cls(**app_definition_json)\n
"},{"location":"trulens_eval/api/appdefinition/#trulens_eval.trulens_eval.schema.AppDefinition.get_loadable_apps","title":"
get_loadable_apps() staticmethod","text":"
Gets a list of all of the loadable apps. This is those that have initial_app_loader_dump set.
Source code in
trulens_eval/trulens_eval/schema.py @staticmethod\ndef get_loadable_apps():\n # EXPERIMENTAL\n\"\"\"\n Gets a list of all of the loadable apps. This is those that have\n `initial_app_loader_dump` set.\n \"\"\"\n\n rets = []\n\n from trulens_eval import Tru\n\n tru = Tru()\n\n apps = tru.get_apps()\n for app in apps:\n dump = app['initial_app_loader_dump']\n if dump is not None:\n rets.append(app)\n\n return rets\n
"},{"location":"trulens_eval/api/appdefinition/#trulens_eval.trulens_eval.schema.AppDefinition.new_session","title":"
new_session(app_definition_json, initial_app_loader=None) staticmethod","text":"
Create a copy of the json serialized app with the enclosed app being initialized to its initial state before any records are produced (i.e. blank memory).
Source code in
trulens_eval/trulens_eval/schema.py @staticmethod\ndef new_session(\n app_definition_json: JSON,\n initial_app_loader: Optional[Callable] = None\n) -> 'AppDefinition':\n\"\"\"\n Create a copy of the json serialized app with the enclosed app being\n initialized to its initial state before any records are produced (i.e.\n blank memory).\n \"\"\"\n\n serial_bytes_json: Optional[JSON] = app_definition_json[\n 'initial_app_loader_dump']\n\n if initial_app_loader is None:\n assert serial_bytes_json is not None, \"Cannot create new session without `initial_app_loader`.\"\n\n serial_bytes = SerialBytes.parse_obj(serial_bytes_json)\n\n app = dill.loads(serial_bytes.data)()\n\n else:\n app = initial_app_loader()\n data = dill.dumps(initial_app_loader, recurse=True)\n serial_bytes = SerialBytes(data=data)\n serial_bytes_json = serial_bytes.dict()\n\n app_definition_json['app'] = app\n app_definition_json['initial_app_loader_dump'] = serial_bytes_json\n\n cls: Type[App] = WithClassInfo.get_class(app_definition_json)\n\n return cls.parse_obj(app_definition_json)\n
"},{"location":"trulens_eval/api/appdefinition/#trulens_eval.trulens_eval.schema.AppDefinition.select_inputs","title":"
select_inputs() classmethod","text":"
Get the path to the main app's call inputs.
Source code in
trulens_eval/trulens_eval/schema.py @classmethod\ndef select_inputs(cls) -> JSONPath:\n\"\"\"\n Get the path to the main app's call inputs.\n \"\"\"\n\n return getattr(\n Select.RecordCalls,\n cls.root_callable.default_factory().name\n ).args\n
"},{"location":"trulens_eval/api/appdefinition/#trulens_eval.trulens_eval.schema.AppDefinition.select_outputs","title":"
select_outputs() classmethod","text":"
Get the path to the main app's call outputs.
Source code in
trulens_eval/trulens_eval/schema.py @classmethod\ndef select_outputs(cls) -> JSONPath:\n\"\"\"\n Get the path to the main app's call outputs.\n \"\"\"\n\n return getattr(\n Select.RecordCalls,\n cls.root_callable.default_factory().name\n ).rets\n
"},{"location":"trulens_eval/api/bedrock_provider/","title":"AWS Bedrock APIs","text":"
Below is how you can instantiate AWS Bedrock as a provider. Amazon Bedrock is a fully managed service that makes FMs from leading AI startups and Amazon available via an API, so you can choose from a wide range of FMs to find the model that is best suited for your use case
All feedback functions listed in the base LLMProvider class can be run with AWS Bedrock.
Bases: LLMProvider
Source code in
trulens_eval/trulens_eval/feedback/provider/bedrock.py class Bedrock(LLMProvider):\n model_id: str\n region_name: str\n\n def __init__(\n self,\n *args,\n model_id=\"amazon.titan-tg1-large\",\n region_name=\"us-east-1\",\n **kwargs\n ):\n # NOTE(piotrm): pydantic adds endpoint to the signature of this\n # constructor if we don't include it explicitly, even though we set it\n # down below. Adding it as None here as a temporary hack.\n\"\"\"\n A set of AWS Feedback Functions.\n\n Parameters:\n\n - model_id (str, optional): The specific model id. Defaults to\n \"amazon.titan-tg1-large\".\n - region_name (str, optional): The specific AWS region name. Defaults to\n \"us-east-1\"\n\n - All other args/kwargs passed to the boto3 client constructor.\n \"\"\"\n # TODO: why was self_kwargs required here independently of kwargs?\n self_kwargs = dict()\n self_kwargs.update(**kwargs)\n\n self_kwargs['model_id'] = model_id\n self_kwargs['region_name'] = region_name\n self_kwargs['endpoint'] = BedrockEndpoint(\n region_name=region_name, *args, **kwargs\n )\n\n super().__init__(\n **self_kwargs\n ) # need to include pydantic.BaseModel.__init__\n\n # LLMProvider requirement\n def _create_chat_completion(\n self,\n prompt: Optional[str] = None,\n messages: Optional[Sequence[Dict]] = None,\n **kwargs\n ) -> str:\n\n # NOTE(joshr): only tested with sso auth\n import json\n\n import boto3\n bedrock = boto3.client(service_name='bedrock-runtime')\n\n assert prompt is not None, \"Bedrock can only operate on `prompt`, not `messages`.\"\n\n body = json.dumps({\"inputText\": prompt})\n\n modelId = self.model_id\n\n response = bedrock.invoke_model(body=body, modelId=modelId)\n\n response_body = json.loads(response.get('body').read()\n ).get('results')[0][\"outputText\"]\n # text\n return response_body\n
"},{"location":"trulens_eval/api/bedrock_provider/#trulens_eval.trulens_eval.feedback.provider.bedrock.Bedrock.__init__","title":"
__init__(*args, model_id='amazon.titan-tg1-large', region_name='us-east-1', **kwargs)","text":"
A set of AWS Feedback Functions.
- model_id (str, optional): The specific model id. Defaults to \"amazon.titan-tg1-large\".
-
region_name (str, optional): The specific AWS region name. Defaults to \"us-east-1\"
-
All other args/kwargs passed to the boto3 client constructor.
Source code in
trulens_eval/trulens_eval/feedback/provider/bedrock.py def __init__(\n self,\n *args,\n model_id=\"amazon.titan-tg1-large\",\n region_name=\"us-east-1\",\n **kwargs\n):\n # NOTE(piotrm): pydantic adds endpoint to the signature of this\n # constructor if we don't include it explicitly, even though we set it\n # down below. Adding it as None here as a temporary hack.\n\"\"\"\n A set of AWS Feedback Functions.\n\n Parameters:\n\n - model_id (str, optional): The specific model id. Defaults to\n \"amazon.titan-tg1-large\".\n - region_name (str, optional): The specific AWS region name. Defaults to\n \"us-east-1\"\n\n - All other args/kwargs passed to the boto3 client constructor.\n \"\"\"\n # TODO: why was self_kwargs required here independently of kwargs?\n self_kwargs = dict()\n self_kwargs.update(**kwargs)\n\n self_kwargs['model_id'] = model_id\n self_kwargs['region_name'] = region_name\n self_kwargs['endpoint'] = BedrockEndpoint(\n region_name=region_name, *args, **kwargs\n )\n\n super().__init__(\n **self_kwargs\n ) # need to include pydantic.BaseModel.__init__\n
"},{"location":"trulens_eval/api/feedback/","title":"Feedback Function APIs","text":"
Below are out of the box feedback functions and how to instantiate them.
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider","title":"
LLMProvider","text":"
Bases: Provider, ABC
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py class LLMProvider(Provider, ABC):\n\n model_engine: str\n\n def __init__(self, *args, **kwargs):\n # NOTE(piotrm): pydantic adds endpoint to the signature of this\n # constructor if we don't include it explicitly, even though we set it\n # down below. Adding it as None here as a temporary hack\n\n # TODO: why was self_kwargs required here independently of kwargs?\n self_kwargs = dict()\n self_kwargs.update(**kwargs)\n\n super().__init__(\n **self_kwargs\n ) # need to include pydantic.BaseModel.__init__\n\n @abstractmethod\n def _create_chat_completion(\n self,\n prompt: Optional[str] = None,\n messages: Optional[Sequence[Dict]] = None,\n **kwargs\n ) -> str:\n\"\"\"\n Chat Completion Model\n\n Returns:\n str: Completion model response.\n \"\"\"\n # text\n pass\n\n def _find_relevant_string(self, full_source: str, hypothesis: str) -> str:\n return self.endpoint.run_me(\n lambda: self._create_chat_completion(\n prompt=str.format(\n prompts.SYSTEM_FIND_SUPPORTING,\n prompt=full_source,\n ) + \"\\n\" + str.\n format(prompts.USER_FIND_SUPPORTING, response=hypothesis)\n )\n )\n\n def _summarized_groundedness(self, premise: str, hypothesis: str) -> float:\n\"\"\"\n A groundedness measure best used for summarized premise against simple\n hypothesis. This LLM implementation uses information overlap prompts.\n\n Args:\n premise (str): Summarized source sentences.\n hypothesis (str): Single statement setnece.\n\n Returns:\n float: Information Overlap\n \"\"\"\n return re_0_10_rating(\n self.endpoint.run_me(\n lambda: self._create_chat_completion(\n prompt=str.format(\n prompts.LLM_GROUNDEDNESS,\n premise=premise,\n hypothesis=hypothesis,\n )\n )\n )\n ) / 10.0\n\n def _groundedness_doc_in_out(self, premise: str, hypothesis: str) -> str:\n\"\"\"\n An LLM prompt using the entire document for premise and entire statement\n document for hypothesis.\n\n Args:\n premise (str): A source document\n hypothesis (str): A statement to check\n\n Returns:\n str: An LLM response using a scorecard template\n \"\"\"\n return self.endpoint.run_me(\n lambda: self._create_chat_completion(\n prompt=str.format(prompts.LLM_GROUNDEDNESS_FULL_SYSTEM,) + str.\n format(\n prompts.LLM_GROUNDEDNESS_FULL_PROMPT,\n premise=premise,\n hypothesis=hypothesis\n )\n )\n )\n\n def _extract_score_and_reasons_from_response(\n self,\n system_prompt: str,\n user_prompt: Optional[str] = None,\n normalize: float = 10.0\n ) -> Union[float, Tuple[float, Dict]]:\n\"\"\"\n Extractor for our LLM prompts. If CoT is used; it will look for\n \"Supporting Evidence\" template. Otherwise, it will look for the typical\n 0-10 scoring.\n\n Args:\n system_prompt (str): A pre-formated system prompt\n\n Returns:\n The score and reason metadata if available.\n \"\"\"\n llm_messages = [{\"role\": \"system\", \"content\": system_prompt}]\n if user_prompt is not None:\n llm_messages.append({\"role\": \"user\", \"content\": user_prompt})\n\n response = self.endpoint.run_me(\n lambda: self._create_chat_completion(messages=llm_messages)\n )\n if \"Supporting Evidence\" in response:\n score = 0.0\n supporting_evidence = \"\"\n for line in response.split('\\n'):\n if \"Score\" in line:\n score = re_0_10_rating(line) / normalize\n if \"Criteria\" in line:\n parts = line.split(\":\")\n if len(parts) > 1:\n criteria = \":\".join(parts[1:]).strip()\n if \"Supporting Evidence\" in line:\n parts = line.split(\":\")\n if len(parts) > 1:\n supporting_evidence = \":\".join(parts[1:]).strip()\n reasons = {\n 'reason':\n (\n f\"{'Criteria: ' + str(criteria) + ' ' if criteria else ''}\\n\"\n f\"{'Supporting Evidence: ' + str(supporting_evidence) if supporting_evidence else ''}\"\n )\n }\n return score, reasons\n else:\n return re_0_10_rating(response) / normalize\n\n def qs_relevance(self, question: str, statement: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the relevance of the statement to the question.\n\n ```python\n feedback = Feedback(provider.qs_relevance).on_input_output() \n ```\n The `on_input_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Usage on RAG Contexts:\n\n ```python\n feedback = Feedback(provider.qs_relevance).on_input().on(\n TruLlama.select_source_nodes().node.text # See note below\n ).aggregate(np.mean) \n ```\n\n The `on(...)` selector can be changed. See [Feedback Function Guide :\n Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Args:\n question (str): A question being asked. \n statement (str): A statement to the question.\n\n Returns:\n float: A value between 0.0 (not relevant) and 1.0 (relevant).\n \"\"\"\n return re_0_10_rating(\n self.endpoint.run_me(\n lambda: self._create_chat_completion(\n prompt=str.format(\n prompts.QS_RELEVANCE,\n question=question,\n statement=statement\n )\n )\n )\n ) / 10\n\n def qs_relevance_with_cot_reasons(\n self, question: str, statement: str\n ) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a\n template to check the relevance of the statement to the question.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```\n feedback = Feedback(provider.qs_relevance_with_cot_reasons).on_input_output() \n ```\n The `on_input_output()` selector can be changed. See [Feedback Function Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Usage on RAG Contexts:\n ```\n feedback = Feedback(provider.qs_relevance_with_cot_reasons).on_input().on(\n TruLlama.select_source_nodes().node.text # See note below\n ).aggregate(np.mean) \n\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n\n Args:\n question (str): A question being asked. \n statement (str): A statement to the question.\n\n Returns:\n float: A value between 0 and 1. 0 being \"not relevant\" and 1 being \"relevant\".\n \"\"\"\n system_prompt = str.format(\n prompts.QS_RELEVANCE, question=question, statement=statement\n )\n system_prompt = system_prompt.replace(\n \"RELEVANCE:\", prompts.COT_REASONS_TEMPLATE\n )\n return self.endpoint.run_me(\n lambda: self.\n _extract_score_and_reasons_from_response(system_prompt)\n )\n\n def relevance(self, prompt: str, response: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a\n template to check the relevance of the response to a prompt.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.relevance).on_input_output()\n ```\n\n The `on_input_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Usage on RAG Contexts:\n\n ```python\n feedback = Feedback(provider.relevance).on_input().on(\n TruLlama.select_source_nodes().node.text # See note below\n ).aggregate(np.mean) \n ```\n\n The `on(...)` selector can be changed. See [Feedback Function Guide :\n Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Parameters:\n prompt (str): A text prompt to an agent.\n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0 and 1. 0 being \"not relevant\" and 1 being\n \"relevant\".\n \"\"\"\n return re_0_10_rating(\n self.endpoint.run_me(\n lambda: self._create_chat_completion(\n prompt=str.format(\n prompts.PR_RELEVANCE, prompt=prompt, response=response\n )\n )\n )\n ) / 10.0\n\n def relevance_with_cot_reasons(self, prompt: str, response: str) -> float:\n\"\"\"\n Uses chat completion Model. A function that completes a template to\n check the relevance of the response to a prompt. Also uses chain of\n thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.relevance_with_cot_reasons).on_input_output()\n ```\n\n The `on_input_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Usage on RAG Contexts:\n ```python\n\n feedback = Feedback(provider.relevance_with_cot_reasons).on_input().on(\n TruLlama.select_source_nodes().node.text # See note below\n ).aggregate(np.mean) \n ```\n\n The `on(...)` selector can be changed. See [Feedback Function Guide :\n Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Args:\n prompt (str): A text prompt to an agent. \n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0 and 1. 0 being \"not relevant\" and 1 being\n \"relevant\".\n \"\"\"\n system_prompt = str.format(\n prompts.PR_RELEVANCE, prompt=prompt, response=response\n )\n system_prompt = system_prompt.replace(\n \"RELEVANCE:\", prompts.COT_REASONS_TEMPLATE\n )\n return self._extract_score_and_reasons_from_response(system_prompt)\n\n def sentiment(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the sentiment of some text.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.sentiment).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Parameters:\n text (str): A prompt to an agent.\n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0 and 1. 0 being \"negative sentiment\" and 1\n being \"positive sentiment\".\n \"\"\"\n\n return re_0_10_rating(\n self.endpoint.run_me(\n lambda: self._create_chat_completion(\n prompt=prompts.SENTIMENT_SYSTEM_PROMPT + text\n )\n )\n ) / 10.0\n\n def sentiment_with_cot_reasons(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a\n template to check the sentiment of some text.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n\n ```python\n feedback = Feedback(provider.sentiment_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (negative sentiment) and 1.0 (positive sentiment).\n \"\"\"\n\n system_prompt = prompts.SENTIMENT_SYSTEM_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def model_agreement(self, prompt: str, response: str) -> float:\n\"\"\"\n Uses chat completion model. A function that gives a chat completion model the same\n prompt and gets a response, encouraging truthfulness. A second template\n is given to the model with a prompt that the original response is\n correct, and measures whether previous chat completion response is similar.\n\n **Usage:**\n\n ```python\n feedback = Feedback(provider.model_agreement).on_input_output() \n ```\n\n The `on_input_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Parameters:\n prompt (str): A text prompt to an agent.\n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0.0 (not in agreement) and 1.0 (in agreement).\n \"\"\"\n warnings.warn(\n \"`model_agreement` has been deprecated. \"\n \"Use `GroundTruthAgreement(ground_truth)` instead.\",\n DeprecationWarning\n )\n chat_response = self._create_chat_completion(\n prompt=prompts.CORRECT_SYSTEM_PROMPT\n )\n agreement_txt = self._get_answer_agreement(\n prompt, response, chat_response\n )\n return re_0_10_rating(agreement_txt) / 10.0\n\n # TODO: figure out where text is used.\n def _langchain_evaluate(self, text: str, system_prompt: str) -> float:\n\"\"\"\n Uses chat completion model. A general function that completes a template\n to evaluate different aspects of some text. Prompt credit to Langchain\n Eval.\n\n Parameters:\n text (str): A prompt to an agent.\n system_prompt (str): The specific system prompt for evaluation.\n\n Returns:\n float: A value between 0.0 and 1.0, representing the specified\n evaluation.\n \"\"\"\n\n return re_0_10_rating(\n self.endpoint.\n run_me(lambda: self._create_chat_completion(prompt=system_prompt))\n ) / 10.0\n\n def conciseness(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the conciseness of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n\n ```python\n feedback = Feedback(provider.conciseness).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Parameters:\n text (str): A prompt to an agent.\n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0.0 (not concise) and 1.0 (concise).\n \"\"\"\n return self._langchain_evaluate(\n text, prompts.LANGCHAIN_CONCISENESS_PROMPT\n )\n\n def correctness(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the correctness of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.correctness).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Parameters:\n text (str): A prompt to an agent. response (str): The agent's\n response to the prompt.\n\n Returns:\n float: A value between 0.0 (not correct) and 1.0 (correct).\n \"\"\"\n system_prompt = prompts.LANGCHAIN_CORRECTNESS_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def correctness_with_cot_reasons(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the correctness of some text. Prompt credit to Langchain Eval.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.correctness_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not correct) and 1.0 (correct).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_CORRECTNESS_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def coherence(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a\n template to check the coherence of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.coherence).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not coherent) and 1.0 (coherent).\n \"\"\"\n system_prompt = prompts.LANGCHAIN_COHERENCE_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def coherence_with_cot_reasons(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the coherence of some text. Prompt credit to Langchain Eval. Also\n uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.coherence_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not coherent) and 1.0 (coherent).\n \"\"\"\n system_prompt = prompts.LANGCHAIN_COHERENCE_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def harmfulness(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the harmfulness of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.harmfulness).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not harmful) and 1.0 (harmful)\".\n \"\"\"\n return self._langchain_evaluate(\n text, prompts.LANGCHAIN_HARMFULNESS_PROMPT\n )\n\n def harmfulness_with_cot_reasons(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the harmfulness of some text. Prompt credit to Langchain Eval.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.harmfulness_with_cot_reasons).on_output() \n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not harmful) and 1.0 (harmful).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_HARMFULNESS_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def maliciousness(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the maliciousness of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.maliciousness).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not malicious) and 1.0 (malicious).\n \"\"\"\n\n return self._langchain_evaluate(\n text, prompts.LANGCHAIN_MALICIOUSNESS_PROMPT\n )\n\n def maliciousness_with_cot_reasons(self, text: str) -> float:\n\"\"\"\n Uses chat compoletion model. A function that completes a\n template to check the maliciousness of some text. Prompt credit to Langchain Eval.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.maliciousness_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not malicious) and 1.0 (malicious).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_MALICIOUSNESS_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def helpfulness(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the helpfulness of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.helpfulness).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not helpful) and 1.0 (helpful).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_HELPFULNESS_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def helpfulness_with_cot_reasons(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the helpfulness of some text. Prompt credit to Langchain Eval.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.helpfulness_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.o (not helpful) and 1.0 (helpful).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_HELPFULNESS_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def controversiality(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the controversiality of some text. Prompt credit to Langchain\n Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.controversiality).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not controversial) and 1.0\n (controversial).\n \"\"\"\n system_prompt = prompts.LANGCHAIN_CONTROVERSIALITY_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def controversiality_with_cot_reasons(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the controversiality of some text. Prompt credit to Langchain\n Eval. Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.controversiality_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not controversial) and 1.0 (controversial).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_CONTROVERSIALITY_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def misogyny(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the misogyny of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.misogyny).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not misogynistic) and 1.0 (misogynistic).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_MISOGYNY_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def misogyny_with_cot_reasons(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the misogyny of some text. Prompt credit to Langchain Eval. Also\n uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.misogyny_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not misogynistic) and 1.0 (misogynistic).\n \"\"\"\n system_prompt = prompts.LANGCHAIN_MISOGYNY_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def criminality(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the criminality of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.criminality).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not criminal) and 1.0 (criminal).\n\n \"\"\"\n system_prompt = prompts.LANGCHAIN_CRIMINALITY_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def criminality_with_cot_reasons(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the criminality of some text. Prompt credit to Langchain Eval.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.criminality_with_cot_reasons).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not criminal) and 1.0 (criminal).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_CRIMINALITY_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def insensitivity(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the insensitivity of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.insensitivity).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not insensitive) and 1.0 (insensitive).\n \"\"\"\n system_prompt = prompts.LANGCHAIN_INSENSITIVITY_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def insensitivity_with_cot_reasons(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the insensitivity of some text. Prompt credit to Langchain Eval.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.insensitivity_with_cot_reasons).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not insensitive) and 1.0 (insensitive).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_INSENSITIVITY_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n\n def _get_answer_agreement(\n self, prompt: str, response: str, check_response: str\n ) -> str:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check if two answers agree.\n\n Parameters:\n text (str): A prompt to an agent.\n response (str): The agent's response to the prompt.\n check_response(str): The response to check against.\n\n Returns:\n str\n \"\"\"\n\n return self.endpoint.run_me(\n lambda: self._create_chat_completion(\n prompt=(prompts.AGREEMENT_SYSTEM_PROMPT %\n (prompt, response)) + check_response\n )\n )\n\n def summary_with_cot_reasons(self, source: str, summary: str) -> float:\n\"\"\"\n Uses chat completion model. A function that tries to distill main points\n and compares a summary against those main points. This feedback function\n only has a chain of thought implementation as it is extremely important\n in function assessment.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.summary_with_cot_reasons).on_input_output()\n ```\n\n Args:\n source (str): Text corresponding to source material. \n summary (str): Text corresponding to a summary.\n\n Returns:\n float: A value between 0.0 (main points missed) and 1.0 (no main\n points missed).\n \"\"\"\n\n system_prompt = str.format(\n prompts.SUMMARIZATION_PROMPT, source=source, summary=summary\n )\n\n return self._extract_score_and_reasons_from_response(system_prompt)\n\n def stereotypes(self, prompt: str, response: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check adding assumed stereotypes in the response when not present in the\n prompt.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.stereotypes).on_input_output()\n ```\n\n Args:\n prompt (str): A text prompt to an agent. \n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0.0 (no stereotypes assumed) and 1.0\n (stereotypes assumed).\n \"\"\"\n\n system_prompt = str.format(\n prompts.STEREOTYPES_PROMPT, prompt=prompt, response=response\n )\n\n return self._extract_score_and_reasons_from_response(system_prompt)\n\n def stereotypes_with_cot_reasons(self, prompt: str, response: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check adding assumed stereotypes in the response when not present in the\n prompt.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.stereotypes).on_input_output()\n ```\n\n Args:\n prompt (str): A text prompt to an agent. \n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0.0 (no stereotypes assumed) and 1.0\n (stereotypes assumed).\n \"\"\"\n system_prompt = str.format(\n prompts.STEREOTYPES_PROMPT, prompt=prompt, response=response\n )\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n\n return self._extract_score_and_reasons_from_response(system_prompt)\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.coherence","title":"
coherence(text)","text":"
Uses chat completion model. A function that completes a template to check the coherence of some text. Prompt credit to Langchain Eval.
Usage:
feedback = Feedback(provider.coherence).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not coherent) and 1.0 (coherent).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def coherence(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a\n template to check the coherence of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.coherence).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not coherent) and 1.0 (coherent).\n \"\"\"\n system_prompt = prompts.LANGCHAIN_COHERENCE_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.coherence_with_cot_reasons","title":"
coherence_with_cot_reasons(text)","text":"
Uses chat completion model. A function that completes a template to check the coherence of some text. Prompt credit to Langchain Eval. Also uses chain of thought methodology and emits the reasons.
Usage:
feedback = Feedback(provider.coherence_with_cot_reasons).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not coherent) and 1.0 (coherent).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def coherence_with_cot_reasons(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the coherence of some text. Prompt credit to Langchain Eval. Also\n uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.coherence_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not coherent) and 1.0 (coherent).\n \"\"\"\n system_prompt = prompts.LANGCHAIN_COHERENCE_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.conciseness","title":"
conciseness(text)","text":"
Uses chat completion model. A function that completes a template to check the conciseness of some text. Prompt credit to Langchain Eval.
Usage:
feedback = Feedback(provider.conciseness).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str A prompt to an agent.
required
response str The agent's response to the prompt.
required
Returns:
Name Type Description
float float A value between 0.0 (not concise) and 1.0 (concise).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def conciseness(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the conciseness of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n\n ```python\n feedback = Feedback(provider.conciseness).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Parameters:\n text (str): A prompt to an agent.\n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0.0 (not concise) and 1.0 (concise).\n \"\"\"\n return self._langchain_evaluate(\n text, prompts.LANGCHAIN_CONCISENESS_PROMPT\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.controversiality","title":"
controversiality(text)","text":"
Uses chat completion model. A function that completes a template to check the controversiality of some text. Prompt credit to Langchain Eval.
Usage:
feedback = Feedback(provider.controversiality).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not controversial) and 1.0
float (controversial).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def controversiality(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the controversiality of some text. Prompt credit to Langchain\n Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.controversiality).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not controversial) and 1.0\n (controversial).\n \"\"\"\n system_prompt = prompts.LANGCHAIN_CONTROVERSIALITY_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.controversiality_with_cot_reasons","title":"
controversiality_with_cot_reasons(text)","text":"
Uses chat completion model. A function that completes a template to check the controversiality of some text. Prompt credit to Langchain Eval. Also uses chain of thought methodology and emits the reasons.
Usage:
feedback = Feedback(provider.controversiality_with_cot_reasons).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not controversial) and 1.0 (controversial).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def controversiality_with_cot_reasons(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the controversiality of some text. Prompt credit to Langchain\n Eval. Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.controversiality_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not controversial) and 1.0 (controversial).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_CONTROVERSIALITY_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.correctness","title":"
correctness(text)","text":"
Uses chat completion model. A function that completes a template to check the correctness of some text. Prompt credit to Langchain Eval.
Usage:
feedback = Feedback(provider.correctness).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str A prompt to an agent. response (str): The agent's
required
Returns:
Name Type Description
float float A value between 0.0 (not correct) and 1.0 (correct).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def correctness(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the correctness of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.correctness).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Parameters:\n text (str): A prompt to an agent. response (str): The agent's\n response to the prompt.\n\n Returns:\n float: A value between 0.0 (not correct) and 1.0 (correct).\n \"\"\"\n system_prompt = prompts.LANGCHAIN_CORRECTNESS_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.correctness_with_cot_reasons","title":"
correctness_with_cot_reasons(text)","text":"
Uses chat completion model. A function that completes a template to check the correctness of some text. Prompt credit to Langchain Eval. Also uses chain of thought methodology and emits the reasons.
Usage:
feedback = Feedback(provider.correctness_with_cot_reasons).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str Text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not correct) and 1.0 (correct).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def correctness_with_cot_reasons(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the correctness of some text. Prompt credit to Langchain Eval.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.correctness_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not correct) and 1.0 (correct).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_CORRECTNESS_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.criminality","title":"
criminality(text)","text":"
Uses chat completion model. A function that completes a template to check the criminality of some text. Prompt credit to Langchain Eval.
Usage:
feedback = Feedback(provider.criminality).on_output()\n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not criminal) and 1.0 (criminal).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def criminality(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the criminality of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.criminality).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not criminal) and 1.0 (criminal).\n\n \"\"\"\n system_prompt = prompts.LANGCHAIN_CRIMINALITY_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.criminality_with_cot_reasons","title":"
criminality_with_cot_reasons(text)","text":"
Uses chat completion model. A function that completes a template to check the criminality of some text. Prompt credit to Langchain Eval. Also uses chain of thought methodology and emits the reasons.
Usage:
feedback = Feedback(provider.criminality_with_cot_reasons).on_output()\n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not criminal) and 1.0 (criminal).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def criminality_with_cot_reasons(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the criminality of some text. Prompt credit to Langchain Eval.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.criminality_with_cot_reasons).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not criminal) and 1.0 (criminal).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_CRIMINALITY_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.harmfulness","title":"
harmfulness(text)","text":"
Uses chat completion model. A function that completes a template to check the harmfulness of some text. Prompt credit to Langchain Eval.
Usage:
feedback = Feedback(provider.harmfulness).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not harmful) and 1.0 (harmful)\".
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def harmfulness(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the harmfulness of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.harmfulness).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not harmful) and 1.0 (harmful)\".\n \"\"\"\n return self._langchain_evaluate(\n text, prompts.LANGCHAIN_HARMFULNESS_PROMPT\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.harmfulness_with_cot_reasons","title":"
harmfulness_with_cot_reasons(text)","text":"
Uses chat completion model. A function that completes a template to check the harmfulness of some text. Prompt credit to Langchain Eval. Also uses chain of thought methodology and emits the reasons.
Usage: ```python feedback = Feedback(provider.harmfulness_with_cot_reasons).on_output()
Args: text (str): The text to evaluate.
Returns: float: A value between 0.0 (not harmful) and 1.0 (harmful).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def harmfulness_with_cot_reasons(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the harmfulness of some text. Prompt credit to Langchain Eval.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.harmfulness_with_cot_reasons).on_output() \n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not harmful) and 1.0 (harmful).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_HARMFULNESS_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.helpfulness","title":"
helpfulness(text)","text":"
Uses chat completion model. A function that completes a template to check the helpfulness of some text. Prompt credit to Langchain Eval.
Usage:
feedback = Feedback(provider.helpfulness).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not helpful) and 1.0 (helpful).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def helpfulness(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the helpfulness of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.helpfulness).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not helpful) and 1.0 (helpful).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_HELPFULNESS_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.helpfulness_with_cot_reasons","title":"
helpfulness_with_cot_reasons(text)","text":"
Uses chat completion model. A function that completes a template to check the helpfulness of some text. Prompt credit to Langchain Eval. Also uses chain of thought methodology and emits the reasons.
Usage:
feedback = Feedback(provider.helpfulness_with_cot_reasons).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.o (not helpful) and 1.0 (helpful).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def helpfulness_with_cot_reasons(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the helpfulness of some text. Prompt credit to Langchain Eval.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.helpfulness_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.o (not helpful) and 1.0 (helpful).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_HELPFULNESS_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.insensitivity","title":"
insensitivity(text)","text":"
Uses chat completion model. A function that completes a template to check the insensitivity of some text. Prompt credit to Langchain Eval.
Usage:
feedback = Feedback(provider.insensitivity).on_output()\n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not insensitive) and 1.0 (insensitive).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def insensitivity(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the insensitivity of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.insensitivity).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not insensitive) and 1.0 (insensitive).\n \"\"\"\n system_prompt = prompts.LANGCHAIN_INSENSITIVITY_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.insensitivity_with_cot_reasons","title":"
insensitivity_with_cot_reasons(text)","text":"
Uses chat completion model. A function that completes a template to check the insensitivity of some text. Prompt credit to Langchain Eval. Also uses chain of thought methodology and emits the reasons.
Usage:
feedback = Feedback(provider.insensitivity_with_cot_reasons).on_output()\n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not insensitive) and 1.0 (insensitive).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def insensitivity_with_cot_reasons(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the insensitivity of some text. Prompt credit to Langchain Eval.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.insensitivity_with_cot_reasons).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not insensitive) and 1.0 (insensitive).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_INSENSITIVITY_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.maliciousness","title":"
maliciousness(text)","text":"
Uses chat completion model. A function that completes a template to check the maliciousness of some text. Prompt credit to Langchain Eval.
Usage:
feedback = Feedback(provider.maliciousness).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not malicious) and 1.0 (malicious).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def maliciousness(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the maliciousness of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.maliciousness).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not malicious) and 1.0 (malicious).\n \"\"\"\n\n return self._langchain_evaluate(\n text, prompts.LANGCHAIN_MALICIOUSNESS_PROMPT\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.maliciousness_with_cot_reasons","title":"
maliciousness_with_cot_reasons(text)","text":"
Uses chat compoletion model. A function that completes a template to check the maliciousness of some text. Prompt credit to Langchain Eval. Also uses chain of thought methodology and emits the reasons.
Usage:
feedback = Feedback(provider.maliciousness_with_cot_reasons).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not malicious) and 1.0 (malicious).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def maliciousness_with_cot_reasons(self, text: str) -> float:\n\"\"\"\n Uses chat compoletion model. A function that completes a\n template to check the maliciousness of some text. Prompt credit to Langchain Eval.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.maliciousness_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not malicious) and 1.0 (malicious).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_MALICIOUSNESS_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.misogyny","title":"
misogyny(text)","text":"
Uses chat completion model. A function that completes a template to check the misogyny of some text. Prompt credit to Langchain Eval.
Usage:
feedback = Feedback(provider.misogyny).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not misogynistic) and 1.0 (misogynistic).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def misogyny(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the misogyny of some text. Prompt credit to Langchain Eval.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.misogyny).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not misogynistic) and 1.0 (misogynistic).\n \"\"\"\n\n system_prompt = prompts.LANGCHAIN_MISOGYNY_PROMPT\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.misogyny_with_cot_reasons","title":"
misogyny_with_cot_reasons(text)","text":"
Uses chat completion model. A function that completes a template to check the misogyny of some text. Prompt credit to Langchain Eval. Also uses chain of thought methodology and emits the reasons.
Usage:
feedback = Feedback(provider.misogyny_with_cot_reasons).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str The text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not misogynistic) and 1.0 (misogynistic).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def misogyny_with_cot_reasons(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the misogyny of some text. Prompt credit to Langchain Eval. Also\n uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.misogyny_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): The text to evaluate.\n\n Returns:\n float: A value between 0.0 (not misogynistic) and 1.0 (misogynistic).\n \"\"\"\n system_prompt = prompts.LANGCHAIN_MISOGYNY_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.model_agreement","title":"
model_agreement(prompt, response)","text":"
Uses chat completion model. A function that gives a chat completion model the same prompt and gets a response, encouraging truthfulness. A second template is given to the model with a prompt that the original response is correct, and measures whether previous chat completion response is similar.
Usage:
feedback = Feedback(provider.model_agreement).on_input_output() \n
The on_input_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
prompt str A text prompt to an agent.
required
response str The agent's response to the prompt.
required
Returns:
Name Type Description
float float A value between 0.0 (not in agreement) and 1.0 (in agreement).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def model_agreement(self, prompt: str, response: str) -> float:\n\"\"\"\n Uses chat completion model. A function that gives a chat completion model the same\n prompt and gets a response, encouraging truthfulness. A second template\n is given to the model with a prompt that the original response is\n correct, and measures whether previous chat completion response is similar.\n\n **Usage:**\n\n ```python\n feedback = Feedback(provider.model_agreement).on_input_output() \n ```\n\n The `on_input_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Parameters:\n prompt (str): A text prompt to an agent.\n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0.0 (not in agreement) and 1.0 (in agreement).\n \"\"\"\n warnings.warn(\n \"`model_agreement` has been deprecated. \"\n \"Use `GroundTruthAgreement(ground_truth)` instead.\",\n DeprecationWarning\n )\n chat_response = self._create_chat_completion(\n prompt=prompts.CORRECT_SYSTEM_PROMPT\n )\n agreement_txt = self._get_answer_agreement(\n prompt, response, chat_response\n )\n return re_0_10_rating(agreement_txt) / 10.0\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.qs_relevance","title":"
qs_relevance(question, statement)","text":"
Uses chat completion model. A function that completes a template to check the relevance of the statement to the question.
feedback = Feedback(provider.qs_relevance).on_input_output() \n
The
on_input_output() selector can be changed. See Feedback Function Guide
Usage on RAG Contexts:
feedback = Feedback(provider.qs_relevance).on_input().on(\n TruLlama.select_source_nodes().node.text # See note below\n).aggregate(np.mean) \n
The on(...) selector can be changed. See Feedback Function Guide : Selectors
Parameters:
Name Type Description Default
question str A question being asked.
required
statement str A statement to the question.
required
Returns:
Name Type Description
float float A value between 0.0 (not relevant) and 1.0 (relevant).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def qs_relevance(self, question: str, statement: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the relevance of the statement to the question.\n\n ```python\n feedback = Feedback(provider.qs_relevance).on_input_output() \n ```\n The `on_input_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Usage on RAG Contexts:\n\n ```python\n feedback = Feedback(provider.qs_relevance).on_input().on(\n TruLlama.select_source_nodes().node.text # See note below\n ).aggregate(np.mean) \n ```\n\n The `on(...)` selector can be changed. See [Feedback Function Guide :\n Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Args:\n question (str): A question being asked. \n statement (str): A statement to the question.\n\n Returns:\n float: A value between 0.0 (not relevant) and 1.0 (relevant).\n \"\"\"\n return re_0_10_rating(\n self.endpoint.run_me(\n lambda: self._create_chat_completion(\n prompt=str.format(\n prompts.QS_RELEVANCE,\n question=question,\n statement=statement\n )\n )\n )\n ) / 10\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.qs_relevance_with_cot_reasons","title":"
qs_relevance_with_cot_reasons(question, statement)","text":"
Uses chat completion model. A function that completes a template to check the relevance of the statement to the question. Also uses chain of thought methodology and emits the reasons.
Usage:
feedback = Feedback(provider.qs_relevance_with_cot_reasons).on_input_output() \n
The
on_input_output() selector can be changed. See Feedback Function Guide
Usage on RAG Contexts:
feedback = Feedback(provider.qs_relevance_with_cot_reasons).on_input().on(\n TruLlama.select_source_nodes().node.text # See note below\n).aggregate(np.mean) \n
The
on(...) selector can be changed. See Feedback Function Guide : Selectors
Parameters:
Name Type Description Default
question str A question being asked.
required
statement str A statement to the question.
required
Returns:
Name Type Description
float float A value between 0 and 1. 0 being \"not relevant\" and 1 being \"relevant\".
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def qs_relevance_with_cot_reasons(\n self, question: str, statement: str\n) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a\n template to check the relevance of the statement to the question.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n ```\n feedback = Feedback(provider.qs_relevance_with_cot_reasons).on_input_output() \n ```\n The `on_input_output()` selector can be changed. See [Feedback Function Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Usage on RAG Contexts:\n ```\n feedback = Feedback(provider.qs_relevance_with_cot_reasons).on_input().on(\n TruLlama.select_source_nodes().node.text # See note below\n ).aggregate(np.mean) \n\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n\n Args:\n question (str): A question being asked. \n statement (str): A statement to the question.\n\n Returns:\n float: A value between 0 and 1. 0 being \"not relevant\" and 1 being \"relevant\".\n \"\"\"\n system_prompt = str.format(\n prompts.QS_RELEVANCE, question=question, statement=statement\n )\n system_prompt = system_prompt.replace(\n \"RELEVANCE:\", prompts.COT_REASONS_TEMPLATE\n )\n return self.endpoint.run_me(\n lambda: self.\n _extract_score_and_reasons_from_response(system_prompt)\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.relevance","title":"
relevance(prompt, response)","text":"
Uses chat completion model. A function that completes a template to check the relevance of the response to a prompt.
Usage:
feedback = Feedback(provider.relevance).on_input_output()\n
The on_input_output() selector can be changed. See Feedback Function Guide
Usage on RAG Contexts:
feedback = Feedback(provider.relevance).on_input().on(\n TruLlama.select_source_nodes().node.text # See note below\n).aggregate(np.mean) \n
The on(...) selector can be changed. See Feedback Function Guide : Selectors
Parameters:
Name Type Description Default
prompt str A text prompt to an agent.
required
response str The agent's response to the prompt.
required
Returns:
Name Type Description
float float A value between 0 and 1. 0 being \"not relevant\" and 1 being
float \"relevant\".
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def relevance(self, prompt: str, response: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a\n template to check the relevance of the response to a prompt.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.relevance).on_input_output()\n ```\n\n The `on_input_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Usage on RAG Contexts:\n\n ```python\n feedback = Feedback(provider.relevance).on_input().on(\n TruLlama.select_source_nodes().node.text # See note below\n ).aggregate(np.mean) \n ```\n\n The `on(...)` selector can be changed. See [Feedback Function Guide :\n Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Parameters:\n prompt (str): A text prompt to an agent.\n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0 and 1. 0 being \"not relevant\" and 1 being\n \"relevant\".\n \"\"\"\n return re_0_10_rating(\n self.endpoint.run_me(\n lambda: self._create_chat_completion(\n prompt=str.format(\n prompts.PR_RELEVANCE, prompt=prompt, response=response\n )\n )\n )\n ) / 10.0\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.relevance_with_cot_reasons","title":"
relevance_with_cot_reasons(prompt, response)","text":"
Uses chat completion Model. A function that completes a template to check the relevance of the response to a prompt. Also uses chain of thought methodology and emits the reasons.
Usage:
feedback = Feedback(provider.relevance_with_cot_reasons).on_input_output()\n
The on_input_output() selector can be changed. See Feedback Function Guide
Usage on RAG Contexts:
feedback = Feedback(provider.relevance_with_cot_reasons).on_input().on(\n TruLlama.select_source_nodes().node.text # See note below\n).aggregate(np.mean) \n
The on(...) selector can be changed. See Feedback Function Guide : Selectors
Parameters:
Name Type Description Default
prompt str A text prompt to an agent.
required
response str The agent's response to the prompt.
required
Returns:
Name Type Description
float float A value between 0 and 1. 0 being \"not relevant\" and 1 being
float \"relevant\".
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def relevance_with_cot_reasons(self, prompt: str, response: str) -> float:\n\"\"\"\n Uses chat completion Model. A function that completes a template to\n check the relevance of the response to a prompt. Also uses chain of\n thought methodology and emits the reasons.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.relevance_with_cot_reasons).on_input_output()\n ```\n\n The `on_input_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Usage on RAG Contexts:\n ```python\n\n feedback = Feedback(provider.relevance_with_cot_reasons).on_input().on(\n TruLlama.select_source_nodes().node.text # See note below\n ).aggregate(np.mean) \n ```\n\n The `on(...)` selector can be changed. See [Feedback Function Guide :\n Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Args:\n prompt (str): A text prompt to an agent. \n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0 and 1. 0 being \"not relevant\" and 1 being\n \"relevant\".\n \"\"\"\n system_prompt = str.format(\n prompts.PR_RELEVANCE, prompt=prompt, response=response\n )\n system_prompt = system_prompt.replace(\n \"RELEVANCE:\", prompts.COT_REASONS_TEMPLATE\n )\n return self._extract_score_and_reasons_from_response(system_prompt)\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.sentiment","title":"
sentiment(text)","text":"
Uses chat completion model. A function that completes a template to check the sentiment of some text.
Usage:
feedback = Feedback(provider.sentiment).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str A prompt to an agent.
required
response str The agent's response to the prompt.
required
Returns:
Name Type Description
float float A value between 0 and 1. 0 being \"negative sentiment\" and 1
float being \"positive sentiment\".
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def sentiment(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check the sentiment of some text.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.sentiment).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Parameters:\n text (str): A prompt to an agent.\n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0 and 1. 0 being \"negative sentiment\" and 1\n being \"positive sentiment\".\n \"\"\"\n\n return re_0_10_rating(\n self.endpoint.run_me(\n lambda: self._create_chat_completion(\n prompt=prompts.SENTIMENT_SYSTEM_PROMPT + text\n )\n )\n ) / 10.0\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.sentiment_with_cot_reasons","title":"
sentiment_with_cot_reasons(text)","text":"
Uses chat completion model. A function that completes a template to check the sentiment of some text. Also uses chain of thought methodology and emits the reasons.
Usage:
feedback = Feedback(provider.sentiment_with_cot_reasons).on_output() \n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str Text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (negative sentiment) and 1.0 (positive sentiment).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def sentiment_with_cot_reasons(self, text: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a\n template to check the sentiment of some text.\n Also uses chain of thought methodology and emits the reasons.\n\n **Usage:**\n\n ```python\n feedback = Feedback(provider.sentiment_with_cot_reasons).on_output() \n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (negative sentiment) and 1.0 (positive sentiment).\n \"\"\"\n\n system_prompt = prompts.SENTIMENT_SYSTEM_PROMPT\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n return self._extract_score_and_reasons_from_response(\n system_prompt, user_prompt=text\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.stereotypes","title":"
stereotypes(prompt, response)","text":"
Uses chat completion model. A function that completes a template to check adding assumed stereotypes in the response when not present in the prompt.
Usage:
feedback = Feedback(provider.stereotypes).on_input_output()\n
Parameters:
Name Type Description Default
prompt str A text prompt to an agent.
required
response str The agent's response to the prompt.
required
Returns:
Name Type Description
float float A value between 0.0 (no stereotypes assumed) and 1.0
float (stereotypes assumed).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def stereotypes(self, prompt: str, response: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check adding assumed stereotypes in the response when not present in the\n prompt.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.stereotypes).on_input_output()\n ```\n\n Args:\n prompt (str): A text prompt to an agent. \n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0.0 (no stereotypes assumed) and 1.0\n (stereotypes assumed).\n \"\"\"\n\n system_prompt = str.format(\n prompts.STEREOTYPES_PROMPT, prompt=prompt, response=response\n )\n\n return self._extract_score_and_reasons_from_response(system_prompt)\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.stereotypes_with_cot_reasons","title":"
stereotypes_with_cot_reasons(prompt, response)","text":"
Uses chat completion model. A function that completes a template to check adding assumed stereotypes in the response when not present in the prompt.
Usage:
feedback = Feedback(provider.stereotypes).on_input_output()\n
Parameters:
Name Type Description Default
prompt str A text prompt to an agent.
required
response str The agent's response to the prompt.
required
Returns:
Name Type Description
float float A value between 0.0 (no stereotypes assumed) and 1.0
float (stereotypes assumed).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def stereotypes_with_cot_reasons(self, prompt: str, response: str) -> float:\n\"\"\"\n Uses chat completion model. A function that completes a template to\n check adding assumed stereotypes in the response when not present in the\n prompt.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.stereotypes).on_input_output()\n ```\n\n Args:\n prompt (str): A text prompt to an agent. \n response (str): The agent's response to the prompt.\n\n Returns:\n float: A value between 0.0 (no stereotypes assumed) and 1.0\n (stereotypes assumed).\n \"\"\"\n system_prompt = str.format(\n prompts.STEREOTYPES_PROMPT, prompt=prompt, response=response\n )\n system_prompt = system_prompt + prompts.COT_REASONS_TEMPLATE\n\n return self._extract_score_and_reasons_from_response(system_prompt)\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.provider.base.LLMProvider.summary_with_cot_reasons","title":"
summary_with_cot_reasons(source, summary)","text":"
Uses chat completion model. A function that tries to distill main points and compares a summary against those main points. This feedback function only has a chain of thought implementation as it is extremely important in function assessment.
Usage:
feedback = Feedback(provider.summary_with_cot_reasons).on_input_output()\n
Parameters:
Name Type Description Default
source str Text corresponding to source material.
required
summary str Text corresponding to a summary.
required
Returns:
Name Type Description
float float A value between 0.0 (main points missed) and 1.0 (no main
float points missed).
Source code in
trulens_eval/trulens_eval/feedback/provider/base.py def summary_with_cot_reasons(self, source: str, summary: str) -> float:\n\"\"\"\n Uses chat completion model. A function that tries to distill main points\n and compares a summary against those main points. This feedback function\n only has a chain of thought implementation as it is extremely important\n in function assessment.\n\n **Usage:**\n ```python\n feedback = Feedback(provider.summary_with_cot_reasons).on_input_output()\n ```\n\n Args:\n source (str): Text corresponding to source material. \n summary (str): Text corresponding to a summary.\n\n Returns:\n float: A value between 0.0 (main points missed) and 1.0 (no main\n points missed).\n \"\"\"\n\n system_prompt = str.format(\n prompts.SUMMARIZATION_PROMPT, source=source, summary=summary\n )\n\n return self._extract_score_and_reasons_from_response(system_prompt)\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.groundedness.Groundedness","title":"
Groundedness","text":"
Bases: SerialModel, WithClassInfo
Measures Groundedness.
Source code in
trulens_eval/trulens_eval/feedback/groundedness.py class Groundedness(SerialModel, WithClassInfo):\n\"\"\"Measures Groundedness.\n \"\"\"\n groundedness_provider: Provider\n\n def __init__(self, groundedness_provider: Provider = None):\n\"\"\"Instantiates the groundedness providers. Currently the groundedness functions work well with a summarizer.\n This class will use an LLM to find the relevant strings in a text. The groundedness_provider can \n either be an LLM provider (such as OpenAI) or NLI with huggingface.\n\n Usage 1:\n ```\n from trulens_eval.feedback import Groundedness\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n groundedness_imp = Groundedness(groundedness_provider=openai_provider)\n ```\n\n Usage 2:\n ```\n from trulens_eval.feedback import Groundedness\n from trulens_eval.feedback.provider.hugs import Huggingface\n huggingface_provider = Huggingface()\n groundedness_imp = Groundedness(groundedness_provider=huggingface_provider)\n ```\n\n Args:\n groundedness_provider (Provider, optional): groundedness provider options: OpenAI LLM or HuggingFace NLI. Defaults to OpenAI().\n summarize_provider (Provider, optional): Internal Usage for DB serialization.\n \"\"\"\n\n if groundedness_provider is None:\n groundedness_provider = OpenAI()\n super().__init__(\n groundedness_provider=groundedness_provider,\n obj=self # for WithClassInfo\n )\n\n def groundedness_measure(self, source: str, statement: str) -> float:\n\"\"\"A measure to track if the source material supports each sentence in the statement. \n This groundedness measure is faster; but less accurate than `groundedness_measure_with_summarize_step` \n\n Usage on RAG Contexts:\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import Groundedness\n from trulens_eval.feedback.provider.openai import OpenAI\n grounded = feedback.Groundedness(groundedness_provider=OpenAI())\n\n\n f_groundedness = feedback.Feedback(grounded.groundedness_measure).on(\n Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content # See note below\n ).on_output().aggregate(grounded.grounded_statements_aggregator)\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n\n Args:\n source (str): The source that should support the statement\n statement (str): The statement to check groundedness\n\n Returns:\n float: A measure between 0 and 1, where 1 means each sentence is grounded in the source.\n \"\"\"\n logger.warning(\n \"Feedback function `groundedness_measure` was renamed to `groundedness_measure_with_cot_reasons`. The new functionality of `groundedness_measure` function will no longer emit reasons as a lower cost option. It may have reduced accuracy due to not using Chain of Thought reasoning in the scoring.\"\n )\n\n groundedness_scores = {}\n if isinstance(self.groundedness_provider,\n (AzureOpenAI, OpenAI, LiteLLM, Bedrock)):\n groundedness_scores[f\"full_doc_score\"] = re_0_10_rating(\n self.groundedness_provider.\n _groundedness_doc_in_out(source, statement)\n ) / 10\n reason = \"Reasons not supplied for non chain of thought function\"\n elif isinstance(self.groundedness_provider, Huggingface):\n reason = \"\"\n for i, hypothesis in enumerate(\n tqdm(statement.split(\".\"),\n desc=\"Groundendess per statement in source\")):\n plausible_junk_char_min = 4 # very likely \"sentences\" under 4 characters are punctuation, spaces, etc\n if len(hypothesis) > plausible_junk_char_min:\n score = self.groundedness_provider._doc_groundedness(\n premise=source, hypothesis=hypothesis\n )\n reason = reason + str.format(\n prompts.GROUNDEDNESS_REASON_TEMPLATE,\n statement_sentence=hypothesis,\n supporting_evidence=\"[Doc NLI Used full source]\",\n score=score * 10,\n )\n groundedness_scores[f\"statement_{i}\"] = score\n\n return groundedness_scores, {\"reason\": reason}\n\n def groundedness_measure_with_cot_reasons(\n self, source: str, statement: str\n ) -> float:\n\"\"\"A measure to track if the source material supports each sentence in the statement. \n This groundedness measure is faster; but less accurate than `groundedness_measure_with_summarize_step`.\n Also uses chain of thought methodology and emits the reasons.\n\n Usage on RAG Contexts:\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import Groundedness\n from trulens_eval.feedback.provider.openai import OpenAI\n grounded = feedback.Groundedness(groundedness_provider=OpenAI())\n\n\n f_groundedness = feedback.Feedback(grounded.groundedness_measure_with_cot_reasons).on(\n Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content # See note below\n ).on_output().aggregate(grounded.grounded_statements_aggregator)\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n\n Args:\n source (str): The source that should support the statement\n statement (str): The statement to check groundedness\n\n Returns:\n float: A measure between 0 and 1, where 1 means each sentence is grounded in the source.\n \"\"\"\n groundedness_scores = {}\n if isinstance(self.groundedness_provider,\n (AzureOpenAI, OpenAI, LiteLLM, Bedrock)):\n plausible_junk_char_min = 4 # very likely \"sentences\" under 4 characters are punctuation, spaces, etc\n if len(statement) > plausible_junk_char_min:\n reason = self.groundedness_provider._groundedness_doc_in_out(\n source, statement\n )\n i = 0\n for line in reason.split('\\n'):\n if \"Score\" in line:\n groundedness_scores[f\"statement_{i}\"\n ] = re_0_10_rating(line) / 10\n i += 1\n return groundedness_scores, {\"reason\": reason}\n elif isinstance(self.groundedness_provider, Huggingface):\n raise Exception(\n \"Chain of Thought reasoning is only applicable to OpenAI groundedness providers. Instantiate `Groundedness(groundedness_provider=OpenAI())` or use `groundedness_measure` feedback function.\"\n )\n\n def groundedness_measure_with_summarize_step(\n self, source: str, statement: str\n ) -> float:\n\"\"\"A measure to track if the source material supports each sentence in the statement. \n This groundedness measure is more accurate; but slower using a two step process.\n - First find supporting evidence with an LLM\n - Then for each statement sentence, check groundendness\n\n Usage on RAG Contexts:\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import Groundedness\n from trulens_eval.feedback.provider.openai import OpenAI\n grounded = feedback.Groundedness(groundedness_provider=OpenAI())\n\n\n f_groundedness = feedback.Feedback(grounded.groundedness_measure_with_summarize_step).on(\n Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content # See note below\n ).on_output().aggregate(grounded.grounded_statements_aggregator)\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n\n Args:\n source (str): The source that should support the statement\n statement (str): The statement to check groundedness\n\n Returns:\n float: A measure between 0 and 1, where 1 means each sentence is grounded in the source.\n \"\"\"\n groundedness_scores = {}\n reason = \"\"\n for i, hypothesis in enumerate(\n tqdm(statement.split(\".\"),\n desc=\"Groundendess per statement in source\")):\n plausible_junk_char_min = 4 # very likely \"sentences\" under 4 characters are punctuation, spaces, etc\n if len(hypothesis) > plausible_junk_char_min:\n supporting_premise = self.groundedness_provider._find_relevant_string(\n source, hypothesis\n )\n score = self.groundedness_provider._summarized_groundedness(\n premise=supporting_premise, hypothesis=hypothesis\n )\n reason = reason + str.format(\n prompts.GROUNDEDNESS_REASON_TEMPLATE,\n statement_sentence=hypothesis,\n supporting_evidence=supporting_premise,\n score=score * 10,\n )\n groundedness_scores[f\"statement_{i}\"] = score\n return groundedness_scores, {\"reason\": reason}\n\n def grounded_statements_aggregator(\n self, source_statements_multi_output: List[Dict]\n ) -> float:\n\"\"\"Aggregates multi-input, mulit-output information from the groundedness_measure methods.\n\n\n Args:\n source_statements_multi_output (List[Dict]): A list of scores. Each list index is a context. The Dict is a per statement score.\n\n Returns:\n float: for each statement, gets the max groundedness, then averages over that.\n \"\"\"\n all_results = []\n\n statements_to_scores = {}\n\n # Ensure source_statements_multi_output is a list\n if not isinstance(source_statements_multi_output, list):\n source_statements_multi_output = [source_statements_multi_output]\n\n for multi_output in source_statements_multi_output:\n for k in multi_output:\n if k not in statements_to_scores:\n statements_to_scores[k] = []\n statements_to_scores[k].append(multi_output[k])\n\n for k in statements_to_scores:\n all_results.append(np.max(statements_to_scores[k]))\n\n return np.mean(all_results)\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.groundedness.Groundedness.__init__","title":"
__init__(groundedness_provider=None)","text":"
Instantiates the groundedness providers. Currently the groundedness functions work well with a summarizer. This class will use an LLM to find the relevant strings in a text. The groundedness_provider can either be an LLM provider (such as OpenAI) or NLI with huggingface.
Usage 1:
from trulens_eval.feedback import Groundedness\nfrom trulens_eval.feedback.provider.openai import OpenAI\nopenai_provider = OpenAI()\ngroundedness_imp = Groundedness(groundedness_provider=openai_provider)\n
Usage 2:
from trulens_eval.feedback import Groundedness\nfrom trulens_eval.feedback.provider.hugs import Huggingface\nhuggingface_provider = Huggingface()\ngroundedness_imp = Groundedness(groundedness_provider=huggingface_provider)\n
Parameters:
Name Type Description Default
groundedness_provider Provider groundedness provider options: OpenAI LLM or HuggingFace NLI. Defaults to OpenAI().
None summarize_provider Provider Internal Usage for DB serialization.
required Source code in
trulens_eval/trulens_eval/feedback/groundedness.py def __init__(self, groundedness_provider: Provider = None):\n\"\"\"Instantiates the groundedness providers. Currently the groundedness functions work well with a summarizer.\n This class will use an LLM to find the relevant strings in a text. The groundedness_provider can \n either be an LLM provider (such as OpenAI) or NLI with huggingface.\n\n Usage 1:\n ```\n from trulens_eval.feedback import Groundedness\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n groundedness_imp = Groundedness(groundedness_provider=openai_provider)\n ```\n\n Usage 2:\n ```\n from trulens_eval.feedback import Groundedness\n from trulens_eval.feedback.provider.hugs import Huggingface\n huggingface_provider = Huggingface()\n groundedness_imp = Groundedness(groundedness_provider=huggingface_provider)\n ```\n\n Args:\n groundedness_provider (Provider, optional): groundedness provider options: OpenAI LLM or HuggingFace NLI. Defaults to OpenAI().\n summarize_provider (Provider, optional): Internal Usage for DB serialization.\n \"\"\"\n\n if groundedness_provider is None:\n groundedness_provider = OpenAI()\n super().__init__(\n groundedness_provider=groundedness_provider,\n obj=self # for WithClassInfo\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.groundedness.Groundedness.grounded_statements_aggregator","title":"
grounded_statements_aggregator(source_statements_multi_output)","text":"
Aggregates multi-input, mulit-output information from the groundedness_measure methods.
Parameters:
Name Type Description Default
source_statements_multi_output List[Dict] A list of scores. Each list index is a context. The Dict is a per statement score.
required
Returns:
Name Type Description
float float for each statement, gets the max groundedness, then averages over that.
Source code in
trulens_eval/trulens_eval/feedback/groundedness.py def grounded_statements_aggregator(\n self, source_statements_multi_output: List[Dict]\n) -> float:\n\"\"\"Aggregates multi-input, mulit-output information from the groundedness_measure methods.\n\n\n Args:\n source_statements_multi_output (List[Dict]): A list of scores. Each list index is a context. The Dict is a per statement score.\n\n Returns:\n float: for each statement, gets the max groundedness, then averages over that.\n \"\"\"\n all_results = []\n\n statements_to_scores = {}\n\n # Ensure source_statements_multi_output is a list\n if not isinstance(source_statements_multi_output, list):\n source_statements_multi_output = [source_statements_multi_output]\n\n for multi_output in source_statements_multi_output:\n for k in multi_output:\n if k not in statements_to_scores:\n statements_to_scores[k] = []\n statements_to_scores[k].append(multi_output[k])\n\n for k in statements_to_scores:\n all_results.append(np.max(statements_to_scores[k]))\n\n return np.mean(all_results)\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.groundedness.Groundedness.groundedness_measure","title":"
groundedness_measure(source, statement)","text":"
A measure to track if the source material supports each sentence in the statement. This groundedness measure is faster; but less accurate than groundedness_measure_with_summarize_step
Usage on RAG Contexts:
from trulens_eval import Feedback\nfrom trulens_eval.feedback import Groundedness\nfrom trulens_eval.feedback.provider.openai import OpenAI\ngrounded = feedback.Groundedness(groundedness_provider=OpenAI())\n\n\nf_groundedness = feedback.Feedback(grounded.groundedness_measure).on(\n Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content # See note below\n).on_output().aggregate(grounded.grounded_statements_aggregator)\n
The
on(...) selector can be changed. See Feedback Function Guide : Selectors
Parameters:
Name Type Description Default
source str The source that should support the statement
required
statement str The statement to check groundedness
required
Returns:
Name Type Description
float float A measure between 0 and 1, where 1 means each sentence is grounded in the source.
Source code in
trulens_eval/trulens_eval/feedback/groundedness.py def groundedness_measure(self, source: str, statement: str) -> float:\n\"\"\"A measure to track if the source material supports each sentence in the statement. \n This groundedness measure is faster; but less accurate than `groundedness_measure_with_summarize_step` \n\n Usage on RAG Contexts:\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import Groundedness\n from trulens_eval.feedback.provider.openai import OpenAI\n grounded = feedback.Groundedness(groundedness_provider=OpenAI())\n\n\n f_groundedness = feedback.Feedback(grounded.groundedness_measure).on(\n Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content # See note below\n ).on_output().aggregate(grounded.grounded_statements_aggregator)\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n\n Args:\n source (str): The source that should support the statement\n statement (str): The statement to check groundedness\n\n Returns:\n float: A measure between 0 and 1, where 1 means each sentence is grounded in the source.\n \"\"\"\n logger.warning(\n \"Feedback function `groundedness_measure` was renamed to `groundedness_measure_with_cot_reasons`. The new functionality of `groundedness_measure` function will no longer emit reasons as a lower cost option. It may have reduced accuracy due to not using Chain of Thought reasoning in the scoring.\"\n )\n\n groundedness_scores = {}\n if isinstance(self.groundedness_provider,\n (AzureOpenAI, OpenAI, LiteLLM, Bedrock)):\n groundedness_scores[f\"full_doc_score\"] = re_0_10_rating(\n self.groundedness_provider.\n _groundedness_doc_in_out(source, statement)\n ) / 10\n reason = \"Reasons not supplied for non chain of thought function\"\n elif isinstance(self.groundedness_provider, Huggingface):\n reason = \"\"\n for i, hypothesis in enumerate(\n tqdm(statement.split(\".\"),\n desc=\"Groundendess per statement in source\")):\n plausible_junk_char_min = 4 # very likely \"sentences\" under 4 characters are punctuation, spaces, etc\n if len(hypothesis) > plausible_junk_char_min:\n score = self.groundedness_provider._doc_groundedness(\n premise=source, hypothesis=hypothesis\n )\n reason = reason + str.format(\n prompts.GROUNDEDNESS_REASON_TEMPLATE,\n statement_sentence=hypothesis,\n supporting_evidence=\"[Doc NLI Used full source]\",\n score=score * 10,\n )\n groundedness_scores[f\"statement_{i}\"] = score\n\n return groundedness_scores, {\"reason\": reason}\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.groundedness.Groundedness.groundedness_measure_with_cot_reasons","title":"
groundedness_measure_with_cot_reasons(source, statement)","text":"
A measure to track if the source material supports each sentence in the statement. This groundedness measure is faster; but less accurate than groundedness_measure_with_summarize_step. Also uses chain of thought methodology and emits the reasons.
Usage on RAG Contexts:
from trulens_eval import Feedback\nfrom trulens_eval.feedback import Groundedness\nfrom trulens_eval.feedback.provider.openai import OpenAI\ngrounded = feedback.Groundedness(groundedness_provider=OpenAI())\n\n\nf_groundedness = feedback.Feedback(grounded.groundedness_measure_with_cot_reasons).on(\n Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content # See note below\n).on_output().aggregate(grounded.grounded_statements_aggregator)\n
The
on(...) selector can be changed. See Feedback Function Guide : Selectors
Parameters:
Name Type Description Default
source str The source that should support the statement
required
statement str The statement to check groundedness
required
Returns:
Name Type Description
float float A measure between 0 and 1, where 1 means each sentence is grounded in the source.
Source code in
trulens_eval/trulens_eval/feedback/groundedness.py def groundedness_measure_with_cot_reasons(\n self, source: str, statement: str\n) -> float:\n\"\"\"A measure to track if the source material supports each sentence in the statement. \n This groundedness measure is faster; but less accurate than `groundedness_measure_with_summarize_step`.\n Also uses chain of thought methodology and emits the reasons.\n\n Usage on RAG Contexts:\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import Groundedness\n from trulens_eval.feedback.provider.openai import OpenAI\n grounded = feedback.Groundedness(groundedness_provider=OpenAI())\n\n\n f_groundedness = feedback.Feedback(grounded.groundedness_measure_with_cot_reasons).on(\n Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content # See note below\n ).on_output().aggregate(grounded.grounded_statements_aggregator)\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n\n Args:\n source (str): The source that should support the statement\n statement (str): The statement to check groundedness\n\n Returns:\n float: A measure between 0 and 1, where 1 means each sentence is grounded in the source.\n \"\"\"\n groundedness_scores = {}\n if isinstance(self.groundedness_provider,\n (AzureOpenAI, OpenAI, LiteLLM, Bedrock)):\n plausible_junk_char_min = 4 # very likely \"sentences\" under 4 characters are punctuation, spaces, etc\n if len(statement) > plausible_junk_char_min:\n reason = self.groundedness_provider._groundedness_doc_in_out(\n source, statement\n )\n i = 0\n for line in reason.split('\\n'):\n if \"Score\" in line:\n groundedness_scores[f\"statement_{i}\"\n ] = re_0_10_rating(line) / 10\n i += 1\n return groundedness_scores, {\"reason\": reason}\n elif isinstance(self.groundedness_provider, Huggingface):\n raise Exception(\n \"Chain of Thought reasoning is only applicable to OpenAI groundedness providers. Instantiate `Groundedness(groundedness_provider=OpenAI())` or use `groundedness_measure` feedback function.\"\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.groundedness.Groundedness.groundedness_measure_with_summarize_step","title":"
groundedness_measure_with_summarize_step(source, statement)","text":"
A measure to track if the source material supports each sentence in the statement. This groundedness measure is more accurate; but slower using a two step process. - First find supporting evidence with an LLM - Then for each statement sentence, check groundendness
Usage on RAG Contexts:
from trulens_eval import Feedback\nfrom trulens_eval.feedback import Groundedness\nfrom trulens_eval.feedback.provider.openai import OpenAI\ngrounded = feedback.Groundedness(groundedness_provider=OpenAI())\n\n\nf_groundedness = feedback.Feedback(grounded.groundedness_measure_with_summarize_step).on(\n Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content # See note below\n).on_output().aggregate(grounded.grounded_statements_aggregator)\n
The
on(...) selector can be changed. See Feedback Function Guide : Selectors
Parameters:
Name Type Description Default
source str The source that should support the statement
required
statement str The statement to check groundedness
required
Returns:
Name Type Description
float float A measure between 0 and 1, where 1 means each sentence is grounded in the source.
Source code in
trulens_eval/trulens_eval/feedback/groundedness.py def groundedness_measure_with_summarize_step(\n self, source: str, statement: str\n) -> float:\n\"\"\"A measure to track if the source material supports each sentence in the statement. \n This groundedness measure is more accurate; but slower using a two step process.\n - First find supporting evidence with an LLM\n - Then for each statement sentence, check groundendness\n\n Usage on RAG Contexts:\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import Groundedness\n from trulens_eval.feedback.provider.openai import OpenAI\n grounded = feedback.Groundedness(groundedness_provider=OpenAI())\n\n\n f_groundedness = feedback.Feedback(grounded.groundedness_measure_with_summarize_step).on(\n Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content # See note below\n ).on_output().aggregate(grounded.grounded_statements_aggregator)\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n\n Args:\n source (str): The source that should support the statement\n statement (str): The statement to check groundedness\n\n Returns:\n float: A measure between 0 and 1, where 1 means each sentence is grounded in the source.\n \"\"\"\n groundedness_scores = {}\n reason = \"\"\n for i, hypothesis in enumerate(\n tqdm(statement.split(\".\"),\n desc=\"Groundendess per statement in source\")):\n plausible_junk_char_min = 4 # very likely \"sentences\" under 4 characters are punctuation, spaces, etc\n if len(hypothesis) > plausible_junk_char_min:\n supporting_premise = self.groundedness_provider._find_relevant_string(\n source, hypothesis\n )\n score = self.groundedness_provider._summarized_groundedness(\n premise=supporting_premise, hypothesis=hypothesis\n )\n reason = reason + str.format(\n prompts.GROUNDEDNESS_REASON_TEMPLATE,\n statement_sentence=hypothesis,\n supporting_evidence=supporting_premise,\n score=score * 10,\n )\n groundedness_scores[f\"statement_{i}\"] = score\n return groundedness_scores, {\"reason\": reason}\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.groundtruth.GroundTruthAgreement","title":"
GroundTruthAgreement","text":"
Bases: SerialModel, WithClassInfo
Measures Agreement against a Ground Truth.
Source code in
trulens_eval/trulens_eval/feedback/groundtruth.py class GroundTruthAgreement(SerialModel, WithClassInfo):\n\"\"\"Measures Agreement against a Ground Truth.\n \"\"\"\n ground_truth: Union[List[str], FunctionOrMethod]\n provider: Provider\n # Note: the bert scorer object isn't serializable\n # It's a class member because creating it is expensive\n bert_scorer: object\n\n ground_truth_imp: Optional[Callable] = pydantic.Field(exclude=True)\n\n class Config:\n arbitrary_types_allowed = True\n\n def __init__(\n self,\n ground_truth: Union[List, Callable, FunctionOrMethod],\n provider: Provider = None,\n bert_scorer: Optional[\"BERTScorer\"] = None\n ):\n\"\"\"Measures Agreement against a Ground Truth. \n\n Usage 1:\n ```\n from trulens_eval.feedback import GroundTruthAgreement\n golden_set = [\n {\"query\": \"who invented the lightbulb?\", \"response\": \"Thomas Edison\"},\n {\"query\": \"\u00bfquien invento la bombilla?\", \"response\": \"Thomas Edison\"}\n ]\n ground_truth_collection = GroundTruthAgreement(golden_set)\n ```\n\n Usage 2:\n ```\n from trulens_eval.feedback import GroundTruthAgreement\n ground_truth_imp = llm_app\n response = llm_app(prompt)\n ground_truth_collection = GroundTruthAgreement(ground_truth_imp)\n ```\n\n Args:\n ground_truth (Union[Callable, FunctionOrMethod]): A list of query/response pairs or a function or callable that returns a ground truth string given a prompt string.\n bert_scorer (Optional["BERTScorer"], optional): Internal Usage for DB serialization.\n provider (Provider, optional): Internal Usage for DB serialization.\n\n \"\"\"\n provider = OpenAI()\n if isinstance(ground_truth, List):\n ground_truth_imp = None\n elif isinstance(ground_truth, FunctionOrMethod):\n ground_truth_imp = ground_truth.load()\n elif isinstance(ground_truth, Callable):\n ground_truth_imp = ground_truth\n ground_truth = FunctionOrMethod.of_callable(ground_truth)\n elif isinstance(ground_truth, Dict):\n # Serialized FunctionOrMethod?\n ground_truth = FunctionOrMethod.pick(**ground_truth)\n ground_truth_imp = ground_truth.load()\n else:\n raise RuntimeError(\n f\"Unhandled ground_truth type: {type(ground_truth)}.\"\n )\n\n super().__init__(\n ground_truth=ground_truth,\n ground_truth_imp=ground_truth_imp,\n provider=provider,\n bert_scorer=bert_scorer,\n obj=self # for WithClassInfo\n )\n\n def _find_response(self, prompt: str) -> Optional[str]:\n if self.ground_truth_imp is not None:\n return self.ground_truth_imp(prompt)\n\n responses = [\n qr[\"response\"] for qr in self.ground_truth if qr[\"query\"] == prompt\n ]\n if responses:\n return responses[0]\n else:\n return None\n\n def _find_score(self, prompt: str, response: str) -> Optional[float]:\n if self.ground_truth_imp is not None:\n return self.ground_truth_imp(prompt)\n\n responses = [\n qr[\"expected_score\"]\n for qr in self.ground_truth\n if qr[\"query\"] == prompt and qr[\"response\"] == response\n ]\n if responses:\n return responses[0]\n else:\n return None\n\n # TODEP\n def agreement_measure(\n self, prompt: str, response: str\n ) -> Union[float, Tuple[float, Dict[str, str]]]:\n\"\"\"\n Uses OpenAI's Chat GPT Model. A function that that measures\n similarity to ground truth. A second template is given to Chat GPT\n with a prompt that the original response is correct, and measures\n whether previous Chat GPT's response is similar.\n\n **Usage:**\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import GroundTruthAgreement\n golden_set = [\n {\"query\": \"who invented the lightbulb?\", \"response\": \"Thomas Edison\"},\n {\"query\": \"\u00bfquien invento la bombilla?\", \"response\": \"Thomas Edison\"}\n ]\n ground_truth_collection = GroundTruthAgreement(golden_set)\n\n feedback = Feedback(ground_truth_collection.agreement_measure).on_input_output() \n ```\n The `on_input_output()` selector can be changed. See [Feedback Function Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n prompt (str): A text prompt to an agent. \n response (str): The agent's response to the prompt.\n\n Returns:\n - float: A value between 0 and 1. 0 being \"not in agreement\" and 1\n being \"in agreement\".\n - dict: with key 'ground_truth_response'\n \"\"\"\n ground_truth_response = self._find_response(prompt)\n if ground_truth_response:\n agreement_txt = self.provider._get_answer_agreement(\n prompt, response, ground_truth_response\n )\n ret = re_0_10_rating(agreement_txt) / 10, dict(\n ground_truth_response=ground_truth_response\n )\n else:\n ret = np.nan\n\n return ret\n\n def mae(self, prompt: str, response: str, score: float) -> float:\n\"\"\"\n Method to look up the numeric expected score from a golden set and take the differnce.\n\n Primarily used for evaluation of model generated feedback against human feedback\n\n **Usage**\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import GroundTruthAgreement\n\n golden_set =\n {\"query\": \"How many stomachs does a cow have?\", \"response\": \"Cows' diet relies primarily on grazing.\", \"expected_score\": 0.4},\n {\"query\": \"Name some top dental floss brands\", \"response\": \"I don't know\", \"expected_score\": 0.8}\n ]\n ground_truth_collection = GroundTruthAgreement(golden_set)\n\n f_groundtruth = Feedback(ground_truth.mae).on(Select.Record.calls[0].args.args[0]).on(Select.Record.calls[0].args.args[1]).on_output()\n ```\n\n \"\"\"\n\n expected_score = self._find_score(prompt, response)\n if expected_score:\n ret = abs(float(score) - expected_score)\n expected_score = \"{:.2f}\".format(expected_score\n ).rstrip('0').rstrip('.')\n else:\n ret = np.nan\n return ret, {\"expected score\": expected_score}\n\n def bert_score(self, prompt: str,\n response: str) -> Union[float, Tuple[float, Dict[str, str]]]:\n\"\"\"\n Uses BERT Score. A function that that measures\n similarity to ground truth using bert embeddings. \n\n **Usage:**\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import GroundTruthAgreement\n golden_set = [\n {\"query\": \"who invented the lightbulb?\", \"response\": \"Thomas Edison\"},\n {\"query\": \"\u00bfquien invento la bombilla?\", \"response\": \"Thomas Edison\"}\n ]\n ground_truth_collection = GroundTruthAgreement(golden_set)\n\n feedback = Feedback(ground_truth_collection.bert_score).on_input_output() \n ```\n The `on_input_output()` selector can be changed. See [Feedback Function Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n\n Args:\n prompt (str): A text prompt to an agent.\n response (str): The agent's response to the prompt.\n\n Returns:\n - float: A value between 0 and 1. 0 being \"not in agreement\" and 1\n being \"in agreement\".\n - dict: with key 'ground_truth_response'\n \"\"\"\n if self.bert_scorer is None:\n self.bert_scorer = BERTScorer(lang=\"en\", rescale_with_baseline=True)\n ground_truth_response = self._find_response(prompt)\n if ground_truth_response:\n bert_score = self.bert_scorer.score(\n [response], [ground_truth_response]\n )\n ret = bert_score[0].item(), dict(\n ground_truth_response=ground_truth_response\n )\n else:\n ret = np.nan\n\n return ret\n\n # TODEP\n def bleu(self, prompt: str,\n response: str) -> Union[float, Tuple[float, Dict[str, str]]]:\n\"\"\"\n Uses BLEU Score. A function that that measures\n similarity to ground truth using token overlap. \n\n **Usage:**\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import GroundTruthAgreement\n golden_set = [\n {\"query\": \"who invented the lightbulb?\", \"response\": \"Thomas Edison\"},\n {\"query\": \"\u00bfquien invento la bombilla?\", \"response\": \"Thomas Edison\"}\n ]\n ground_truth_collection = GroundTruthAgreement(golden_set)\n\n feedback = Feedback(ground_truth_collection.bleu).on_input_output() \n ```\n The `on_input_output()` selector can be changed. See [Feedback Function Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n prompt (str): A text prompt to an agent. \n response (str): The agent's response to the prompt.\n\n Returns:\n - float: A value between 0 and 1. 0 being \"not in agreement\" and 1\n being \"in agreement\".\n - dict: with key 'ground_truth_response'\n \"\"\"\n bleu = evaluate.load('bleu')\n ground_truth_response = self._find_response(prompt)\n if ground_truth_response:\n bleu_score = bleu.compute(\n predictions=[response], references=[ground_truth_response]\n )\n ret = bleu_score['bleu'], dict(\n ground_truth_response=ground_truth_response\n )\n else:\n ret = np.nan\n\n return ret\n\n # TODEP\n def rouge(self, prompt: str,\n response: str) -> Union[float, Tuple[float, Dict[str, str]]]:\n\"\"\"\n Uses BLEU Score. A function that that measures\n similarity to ground truth using token overlap. \n\n Args:\n prompt (str): A text prompt to an agent. \n response (str): The agent's response to the prompt.\n\n Returns:\n - float: A value between 0 and 1. 0 being \"not in agreement\" and 1\n being \"in agreement\".\n - dict: with key 'ground_truth_response'\n \"\"\"\n rouge = evaluate.load('rouge')\n ground_truth_response = self._find_response(prompt)\n if ground_truth_response:\n rouge_score = rouge.compute(\n predictions=[response], references=[ground_truth_response]\n )\n ret = rouge_score['rouge1'], dict(\n ground_truth_response=ground_truth_response\n )\n else:\n ret = np.nan\n\n return ret\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.groundtruth.GroundTruthAgreement.__init__","title":"
__init__(ground_truth, provider=None, bert_scorer=None)","text":"
Measures Agreement against a Ground Truth.
Usage 1:
from trulens_eval.feedback import GroundTruthAgreement\ngolden_set = [\n {\"query\": \"who invented the lightbulb?\", \"response\": \"Thomas Edison\"},\n {\"query\": \"\u00bfquien invento la bombilla?\", \"response\": \"Thomas Edison\"}\n]\nground_truth_collection = GroundTruthAgreement(golden_set)\n
Usage 2:
from trulens_eval.feedback import GroundTruthAgreement\nground_truth_imp = llm_app\nresponse = llm_app(prompt)\nground_truth_collection = GroundTruthAgreement(ground_truth_imp)\n
Parameters:
Name Type Description Default
ground_truth Union[Callable, FunctionOrMethod] A list of query/response pairs or a function or callable that returns a ground truth string given a prompt string.
required
bert_scorer Optional["BERTScorer"] Internal Usage for DB serialization.
None provider Provider Internal Usage for DB serialization.
None Source code in
trulens_eval/trulens_eval/feedback/groundtruth.py def __init__(\n self,\n ground_truth: Union[List, Callable, FunctionOrMethod],\n provider: Provider = None,\n bert_scorer: Optional[\"BERTScorer\"] = None\n):\n\"\"\"Measures Agreement against a Ground Truth. \n\n Usage 1:\n ```\n from trulens_eval.feedback import GroundTruthAgreement\n golden_set = [\n {\"query\": \"who invented the lightbulb?\", \"response\": \"Thomas Edison\"},\n {\"query\": \"\u00bfquien invento la bombilla?\", \"response\": \"Thomas Edison\"}\n ]\n ground_truth_collection = GroundTruthAgreement(golden_set)\n ```\n\n Usage 2:\n ```\n from trulens_eval.feedback import GroundTruthAgreement\n ground_truth_imp = llm_app\n response = llm_app(prompt)\n ground_truth_collection = GroundTruthAgreement(ground_truth_imp)\n ```\n\n Args:\n ground_truth (Union[Callable, FunctionOrMethod]): A list of query/response pairs or a function or callable that returns a ground truth string given a prompt string.\n bert_scorer (Optional["BERTScorer"], optional): Internal Usage for DB serialization.\n provider (Provider, optional): Internal Usage for DB serialization.\n\n \"\"\"\n provider = OpenAI()\n if isinstance(ground_truth, List):\n ground_truth_imp = None\n elif isinstance(ground_truth, FunctionOrMethod):\n ground_truth_imp = ground_truth.load()\n elif isinstance(ground_truth, Callable):\n ground_truth_imp = ground_truth\n ground_truth = FunctionOrMethod.of_callable(ground_truth)\n elif isinstance(ground_truth, Dict):\n # Serialized FunctionOrMethod?\n ground_truth = FunctionOrMethod.pick(**ground_truth)\n ground_truth_imp = ground_truth.load()\n else:\n raise RuntimeError(\n f\"Unhandled ground_truth type: {type(ground_truth)}.\"\n )\n\n super().__init__(\n ground_truth=ground_truth,\n ground_truth_imp=ground_truth_imp,\n provider=provider,\n bert_scorer=bert_scorer,\n obj=self # for WithClassInfo\n )\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.groundtruth.GroundTruthAgreement.agreement_measure","title":"
agreement_measure(prompt, response)","text":"
Uses OpenAI's Chat GPT Model. A function that that measures similarity to ground truth. A second template is given to Chat GPT with a prompt that the original response is correct, and measures whether previous Chat GPT's response is similar.
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback import GroundTruthAgreement\ngolden_set = [\n {\"query\": \"who invented the lightbulb?\", \"response\": \"Thomas Edison\"},\n {\"query\": \"\u00bfquien invento la bombilla?\", \"response\": \"Thomas Edison\"}\n]\nground_truth_collection = GroundTruthAgreement(golden_set)\n\nfeedback = Feedback(ground_truth_collection.agreement_measure).on_input_output() \n
The
on_input_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
prompt str A text prompt to an agent.
required
response str The agent's response to the prompt.
required
Returns:
Type Description
Union[float, Tuple[float, Dict[str, str]]] - float: A value between 0 and 1. 0 being \"not in agreement\" and 1 being \"in agreement\".
Union[float, Tuple[float, Dict[str, str]]] - dict: with key 'ground_truth_response'
Source code in
trulens_eval/trulens_eval/feedback/groundtruth.py def agreement_measure(\n self, prompt: str, response: str\n) -> Union[float, Tuple[float, Dict[str, str]]]:\n\"\"\"\n Uses OpenAI's Chat GPT Model. A function that that measures\n similarity to ground truth. A second template is given to Chat GPT\n with a prompt that the original response is correct, and measures\n whether previous Chat GPT's response is similar.\n\n **Usage:**\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import GroundTruthAgreement\n golden_set = [\n {\"query\": \"who invented the lightbulb?\", \"response\": \"Thomas Edison\"},\n {\"query\": \"\u00bfquien invento la bombilla?\", \"response\": \"Thomas Edison\"}\n ]\n ground_truth_collection = GroundTruthAgreement(golden_set)\n\n feedback = Feedback(ground_truth_collection.agreement_measure).on_input_output() \n ```\n The `on_input_output()` selector can be changed. See [Feedback Function Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n prompt (str): A text prompt to an agent. \n response (str): The agent's response to the prompt.\n\n Returns:\n - float: A value between 0 and 1. 0 being \"not in agreement\" and 1\n being \"in agreement\".\n - dict: with key 'ground_truth_response'\n \"\"\"\n ground_truth_response = self._find_response(prompt)\n if ground_truth_response:\n agreement_txt = self.provider._get_answer_agreement(\n prompt, response, ground_truth_response\n )\n ret = re_0_10_rating(agreement_txt) / 10, dict(\n ground_truth_response=ground_truth_response\n )\n else:\n ret = np.nan\n\n return ret\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.groundtruth.GroundTruthAgreement.bert_score","title":"
bert_score(prompt, response)","text":"
Uses BERT Score. A function that that measures similarity to ground truth using bert embeddings.
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback import GroundTruthAgreement\ngolden_set = [\n {\"query\": \"who invented the lightbulb?\", \"response\": \"Thomas Edison\"},\n {\"query\": \"\u00bfquien invento la bombilla?\", \"response\": \"Thomas Edison\"}\n]\nground_truth_collection = GroundTruthAgreement(golden_set)\n\nfeedback = Feedback(ground_truth_collection.bert_score).on_input_output() \n
The
on_input_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
prompt str A text prompt to an agent.
required
response str The agent's response to the prompt.
required
Returns:
Type Description
Union[float, Tuple[float, Dict[str, str]]] - float: A value between 0 and 1. 0 being \"not in agreement\" and 1 being \"in agreement\".
Union[float, Tuple[float, Dict[str, str]]] - dict: with key 'ground_truth_response'
Source code in
trulens_eval/trulens_eval/feedback/groundtruth.py def bert_score(self, prompt: str,\n response: str) -> Union[float, Tuple[float, Dict[str, str]]]:\n\"\"\"\n Uses BERT Score. A function that that measures\n similarity to ground truth using bert embeddings. \n\n **Usage:**\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import GroundTruthAgreement\n golden_set = [\n {\"query\": \"who invented the lightbulb?\", \"response\": \"Thomas Edison\"},\n {\"query\": \"\u00bfquien invento la bombilla?\", \"response\": \"Thomas Edison\"}\n ]\n ground_truth_collection = GroundTruthAgreement(golden_set)\n\n feedback = Feedback(ground_truth_collection.bert_score).on_input_output() \n ```\n The `on_input_output()` selector can be changed. See [Feedback Function Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n\n Args:\n prompt (str): A text prompt to an agent.\n response (str): The agent's response to the prompt.\n\n Returns:\n - float: A value between 0 and 1. 0 being \"not in agreement\" and 1\n being \"in agreement\".\n - dict: with key 'ground_truth_response'\n \"\"\"\n if self.bert_scorer is None:\n self.bert_scorer = BERTScorer(lang=\"en\", rescale_with_baseline=True)\n ground_truth_response = self._find_response(prompt)\n if ground_truth_response:\n bert_score = self.bert_scorer.score(\n [response], [ground_truth_response]\n )\n ret = bert_score[0].item(), dict(\n ground_truth_response=ground_truth_response\n )\n else:\n ret = np.nan\n\n return ret\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.groundtruth.GroundTruthAgreement.bleu","title":"
bleu(prompt, response)","text":"
Uses BLEU Score. A function that that measures similarity to ground truth using token overlap.
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback import GroundTruthAgreement\ngolden_set = [\n {\"query\": \"who invented the lightbulb?\", \"response\": \"Thomas Edison\"},\n {\"query\": \"\u00bfquien invento la bombilla?\", \"response\": \"Thomas Edison\"}\n]\nground_truth_collection = GroundTruthAgreement(golden_set)\n\nfeedback = Feedback(ground_truth_collection.bleu).on_input_output() \n
The
on_input_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
prompt str A text prompt to an agent.
required
response str The agent's response to the prompt.
required
Returns:
Type Description
Union[float, Tuple[float, Dict[str, str]]] - float: A value between 0 and 1. 0 being \"not in agreement\" and 1 being \"in agreement\".
Union[float, Tuple[float, Dict[str, str]]] - dict: with key 'ground_truth_response'
Source code in
trulens_eval/trulens_eval/feedback/groundtruth.py def bleu(self, prompt: str,\n response: str) -> Union[float, Tuple[float, Dict[str, str]]]:\n\"\"\"\n Uses BLEU Score. A function that that measures\n similarity to ground truth using token overlap. \n\n **Usage:**\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import GroundTruthAgreement\n golden_set = [\n {\"query\": \"who invented the lightbulb?\", \"response\": \"Thomas Edison\"},\n {\"query\": \"\u00bfquien invento la bombilla?\", \"response\": \"Thomas Edison\"}\n ]\n ground_truth_collection = GroundTruthAgreement(golden_set)\n\n feedback = Feedback(ground_truth_collection.bleu).on_input_output() \n ```\n The `on_input_output()` selector can be changed. See [Feedback Function Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n prompt (str): A text prompt to an agent. \n response (str): The agent's response to the prompt.\n\n Returns:\n - float: A value between 0 and 1. 0 being \"not in agreement\" and 1\n being \"in agreement\".\n - dict: with key 'ground_truth_response'\n \"\"\"\n bleu = evaluate.load('bleu')\n ground_truth_response = self._find_response(prompt)\n if ground_truth_response:\n bleu_score = bleu.compute(\n predictions=[response], references=[ground_truth_response]\n )\n ret = bleu_score['bleu'], dict(\n ground_truth_response=ground_truth_response\n )\n else:\n ret = np.nan\n\n return ret\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.groundtruth.GroundTruthAgreement.mae","title":"
mae(prompt, response, score)","text":"
Method to look up the numeric expected score from a golden set and take the differnce.
Primarily used for evaluation of model generated feedback against human feedback
Usage
from trulens_eval import Feedback\nfrom trulens_eval.feedback import GroundTruthAgreement\n\ngolden_set =\n{\"query\": \"How many stomachs does a cow have?\", \"response\": \"Cows' diet relies primarily on grazing.\", \"expected_score\": 0.4},\n{\"query\": \"Name some top dental floss brands\", \"response\": \"I don't know\", \"expected_score\": 0.8}\n]\nground_truth_collection = GroundTruthAgreement(golden_set)\n\nf_groundtruth = Feedback(ground_truth.mae).on(Select.Record.calls[0].args.args[0]).on(Select.Record.calls[0].args.args[1]).on_output()\n
Source code in
trulens_eval/trulens_eval/feedback/groundtruth.py def mae(self, prompt: str, response: str, score: float) -> float:\n\"\"\"\n Method to look up the numeric expected score from a golden set and take the differnce.\n\n Primarily used for evaluation of model generated feedback against human feedback\n\n **Usage**\n ```\n from trulens_eval import Feedback\n from trulens_eval.feedback import GroundTruthAgreement\n\n golden_set =\n {\"query\": \"How many stomachs does a cow have?\", \"response\": \"Cows' diet relies primarily on grazing.\", \"expected_score\": 0.4},\n {\"query\": \"Name some top dental floss brands\", \"response\": \"I don't know\", \"expected_score\": 0.8}\n ]\n ground_truth_collection = GroundTruthAgreement(golden_set)\n\n f_groundtruth = Feedback(ground_truth.mae).on(Select.Record.calls[0].args.args[0]).on(Select.Record.calls[0].args.args[1]).on_output()\n ```\n\n \"\"\"\n\n expected_score = self._find_score(prompt, response)\n if expected_score:\n ret = abs(float(score) - expected_score)\n expected_score = \"{:.2f}\".format(expected_score\n ).rstrip('0').rstrip('.')\n else:\n ret = np.nan\n return ret, {\"expected score\": expected_score}\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.groundtruth.GroundTruthAgreement.rouge","title":"
rouge(prompt, response)","text":"
Uses BLEU Score. A function that that measures similarity to ground truth using token overlap.
Parameters:
Name Type Description Default
prompt str A text prompt to an agent.
required
response str The agent's response to the prompt.
required
Returns:
Type Description
Union[float, Tuple[float, Dict[str, str]]] - float: A value between 0 and 1. 0 being \"not in agreement\" and 1 being \"in agreement\".
Union[float, Tuple[float, Dict[str, str]]] - dict: with key 'ground_truth_response'
Source code in
trulens_eval/trulens_eval/feedback/groundtruth.py def rouge(self, prompt: str,\n response: str) -> Union[float, Tuple[float, Dict[str, str]]]:\n\"\"\"\n Uses BLEU Score. A function that that measures\n similarity to ground truth using token overlap. \n\n Args:\n prompt (str): A text prompt to an agent. \n response (str): The agent's response to the prompt.\n\n Returns:\n - float: A value between 0 and 1. 0 being \"not in agreement\" and 1\n being \"in agreement\".\n - dict: with key 'ground_truth_response'\n \"\"\"\n rouge = evaluate.load('rouge')\n ground_truth_response = self._find_response(prompt)\n if ground_truth_response:\n rouge_score = rouge.compute(\n predictions=[response], references=[ground_truth_response]\n )\n ret = rouge_score['rouge1'], dict(\n ground_truth_response=ground_truth_response\n )\n else:\n ret = np.nan\n\n return ret\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.embeddings.Embeddings","title":"
Embeddings","text":"
Bases: SerialModel, WithClassInfo
Embedding related feedback function implementations.
Source code in
trulens_eval/trulens_eval/feedback/embeddings.py class Embeddings(SerialModel, WithClassInfo):\n\"\"\"Embedding related feedback function implementations.\n \"\"\"\n _embed_model: 'Embedder' = PrivateAttr()\n\n def __init__(self, embed_model: 'Embedder' = None):\n\"\"\"Instantiates embeddings for feedback functions. \n ```\n f_embed = feedback.Embeddings(embed_model=embed_model)\n ```\n\n Args:\n embed_model ('Embedder'): Supported embedders taken from llama-index: https://gpt-index.readthedocs.io/en/latest/core_modules/model_modules/embeddings/root.html\n \"\"\"\n try:\n import sklearn\n except:\n raise ImportError(REQUIREMENT_SKLEARN)\n\n service_context = ServiceContext.from_defaults(embed_model=embed_model)\n self._embed_model = service_context.embed_model\n super().__init__(obj=self)\n\n def cosine_distance(\n self, query: str, document: str\n ) -> Union[float, Tuple[float, Dict[str, str]]]:\n\"\"\"\n Runs cosine distance on the query and document embeddings\n\n **Usage:**\n ```\n # Below is just one example. See supported embedders: https://gpt-index.readthedocs.io/en/latest/core_modules/model_modules/embeddings/root.html\n from langchain.embeddings.openai import OpenAIEmbeddings\n\n model_name = 'text-embedding-ada-002'\n\n embed_model = OpenAIEmbeddings(\n model=model_name,\n openai_api_key=OPENAI_API_KEY\n )\n\n # Create the feedback function\n f_embed = feedback.Embeddings(embed_model=embed_model)\n f_embed_dist = feedback.Feedback(f_embed.cosine_distance).on_input().on(Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content)\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Args:\n query (str): A text prompt to a vector DB. \n document (str): The document returned from the vector DB.\n\n Returns:\n - float: the embedding vector distance\n \"\"\"\n import sklearn\n query_embed = np.asarray(\n self._embed_model.get_query_embedding(query)\n ).reshape(\n 1, -1\n ) # sklearn expects 2d array (first dimension number of samples)\n document_embed = np.asarray(\n self._embed_model.get_text_embedding(document)\n ).reshape(\n 1, -1\n ) # sklearn expects 2d array (first dimension number of samples)\n\n return sklearn.metrics.pairwise.cosine_distances(\n query_embed, document_embed\n )[0][\n 0\n ] # final results will be dimensions (sample query x sample doc) === (1,1)\n\n def manhattan_distance(\n self, query: str, document: str\n ) -> Union[float, Tuple[float, Dict[str, str]]]:\n\"\"\"\n Runs L1 distance on the query and document embeddings\n\n **Usage:**\n ```\n # Below is just one example. See supported embedders: https://gpt-index.readthedocs.io/en/latest/core_modules/model_modules/embeddings/root.html\n from langchain.embeddings.openai import OpenAIEmbeddings\n\n model_name = 'text-embedding-ada-002'\n\n embed_model = OpenAIEmbeddings(\n model=model_name,\n openai_api_key=OPENAI_API_KEY\n )\n\n # Create the feedback function\n f_embed = feedback.Embeddings(embed_model=embed_model)\n f_embed_dist = feedback.Feedback(f_embed.manhattan_distance).on_input().on(Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content)\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Args:\n query (str): A text prompt to a vector DB. \n document (str): The document returned from the vector DB.\n\n Returns:\n - float: the embedding vector distance\n \"\"\"\n import sklearn\n query_embed = np.asarray(\n self._embed_model.get_query_embedding(query)\n ).reshape(\n 1, -1\n ) # sklearn expects 2d array (first dimension number of samples)\n document_embed = np.asarray(\n self._embed_model.get_text_embedding(document)\n ).reshape(\n 1, -1\n ) # sklearn expects 2d array (first dimension number of samples)\n\n return sklearn.metrics.pairwise.manhattan_distances(\n query_embed, document_embed\n )[0][\n 0\n ] # final results will be dimensions (sample query x sample doc) === (1,1)\n\n def euclidean_distance(\n self, query: str, document: str\n ) -> Union[float, Tuple[float, Dict[str, str]]]:\n\"\"\"\n Runs L2 distance on the query and document embeddings\n\n **Usage:**\n ```\n # Below is just one example. See supported embedders: https://gpt-index.readthedocs.io/en/latest/core_modules/model_modules/embeddings/root.html\n from langchain.embeddings.openai import OpenAIEmbeddings\n\n model_name = 'text-embedding-ada-002'\n\n embed_model = OpenAIEmbeddings(\n model=model_name,\n openai_api_key=OPENAI_API_KEY\n )\n\n # Create the feedback function\n f_embed = feedback.Embeddings(embed_model=embed_model)\n f_embed_dist = feedback.Feedback(f_embed.euclidean_distance).on_input().on(Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content)\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Args:\n query (str): A text prompt to a vector DB. \n document (str): The document returned from the vector DB.\n\n Returns:\n - float: the embedding vector distance\n \"\"\"\n import sklearn\n query_embed = np.asarray(\n self._embed_model.get_query_embedding(query)\n ).reshape(\n 1, -1\n ) # sklearn expects 2d array (first dimension number of samples)\n document_embed = np.asarray(\n self._embed_model.get_text_embedding(document)\n ).reshape(\n 1, -1\n ) # sklearn expects 2d array (first dimension number of samples)\n\n return sklearn.metrics.pairwise.euclidean_distances(\n query_embed, document_embed\n )[0][\n 0\n ] # final results will be dimensions (sample query x sample doc) === (1,1)\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.embeddings.Embeddings.__init__","title":"
__init__(embed_model=None)","text":"
Instantiates embeddings for feedback functions.
f_embed = feedback.Embeddings(embed_model=embed_model)\n
Parameters:
Name Type Description Default
embed_model Embedder Supported embedders taken from llama-index: https://gpt-index.readthedocs.io/en/latest/core_modules/model_modules/embeddings/root.html
None Source code in
trulens_eval/trulens_eval/feedback/embeddings.py def __init__(self, embed_model: 'Embedder' = None):\n\"\"\"Instantiates embeddings for feedback functions. \n ```\n f_embed = feedback.Embeddings(embed_model=embed_model)\n ```\n\n Args:\n embed_model ('Embedder'): Supported embedders taken from llama-index: https://gpt-index.readthedocs.io/en/latest/core_modules/model_modules/embeddings/root.html\n \"\"\"\n try:\n import sklearn\n except:\n raise ImportError(REQUIREMENT_SKLEARN)\n\n service_context = ServiceContext.from_defaults(embed_model=embed_model)\n self._embed_model = service_context.embed_model\n super().__init__(obj=self)\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.embeddings.Embeddings.cosine_distance","title":"
cosine_distance(query, document)","text":"
Runs cosine distance on the query and document embeddings
Usage:
# Below is just one example. See supported embedders: https://gpt-index.readthedocs.io/en/latest/core_modules/model_modules/embeddings/root.html\nfrom langchain.embeddings.openai import OpenAIEmbeddings\n\nmodel_name = 'text-embedding-ada-002'\n\nembed_model = OpenAIEmbeddings(\n model=model_name,\n openai_api_key=OPENAI_API_KEY\n)\n\n# Create the feedback function\nf_embed = feedback.Embeddings(embed_model=embed_model)\nf_embed_dist = feedback.Feedback(f_embed.cosine_distance).on_input().on(Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content)\n
The
on(...) selector can be changed. See Feedback Function Guide : Selectors
Parameters:
Name Type Description Default
query str A text prompt to a vector DB.
required
document str The document returned from the vector DB.
required
Returns:
Type Description
Union[float, Tuple[float, Dict[str, str]]] - float: the embedding vector distance
Source code in
trulens_eval/trulens_eval/feedback/embeddings.py def cosine_distance(\n self, query: str, document: str\n) -> Union[float, Tuple[float, Dict[str, str]]]:\n\"\"\"\n Runs cosine distance on the query and document embeddings\n\n **Usage:**\n ```\n # Below is just one example. See supported embedders: https://gpt-index.readthedocs.io/en/latest/core_modules/model_modules/embeddings/root.html\n from langchain.embeddings.openai import OpenAIEmbeddings\n\n model_name = 'text-embedding-ada-002'\n\n embed_model = OpenAIEmbeddings(\n model=model_name,\n openai_api_key=OPENAI_API_KEY\n )\n\n # Create the feedback function\n f_embed = feedback.Embeddings(embed_model=embed_model)\n f_embed_dist = feedback.Feedback(f_embed.cosine_distance).on_input().on(Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content)\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Args:\n query (str): A text prompt to a vector DB. \n document (str): The document returned from the vector DB.\n\n Returns:\n - float: the embedding vector distance\n \"\"\"\n import sklearn\n query_embed = np.asarray(\n self._embed_model.get_query_embedding(query)\n ).reshape(\n 1, -1\n ) # sklearn expects 2d array (first dimension number of samples)\n document_embed = np.asarray(\n self._embed_model.get_text_embedding(document)\n ).reshape(\n 1, -1\n ) # sklearn expects 2d array (first dimension number of samples)\n\n return sklearn.metrics.pairwise.cosine_distances(\n query_embed, document_embed\n )[0][\n 0\n ] # final results will be dimensions (sample query x sample doc) === (1,1)\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.embeddings.Embeddings.euclidean_distance","title":"
euclidean_distance(query, document)","text":"
Runs L2 distance on the query and document embeddings
Usage:
# Below is just one example. See supported embedders: https://gpt-index.readthedocs.io/en/latest/core_modules/model_modules/embeddings/root.html\nfrom langchain.embeddings.openai import OpenAIEmbeddings\n\nmodel_name = 'text-embedding-ada-002'\n\nembed_model = OpenAIEmbeddings(\n model=model_name,\n openai_api_key=OPENAI_API_KEY\n)\n\n# Create the feedback function\nf_embed = feedback.Embeddings(embed_model=embed_model)\nf_embed_dist = feedback.Feedback(f_embed.euclidean_distance).on_input().on(Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content)\n
The
on(...) selector can be changed. See Feedback Function Guide : Selectors
Parameters:
Name Type Description Default
query str A text prompt to a vector DB.
required
document str The document returned from the vector DB.
required
Returns:
Type Description
Union[float, Tuple[float, Dict[str, str]]] - float: the embedding vector distance
Source code in
trulens_eval/trulens_eval/feedback/embeddings.py def euclidean_distance(\n self, query: str, document: str\n) -> Union[float, Tuple[float, Dict[str, str]]]:\n\"\"\"\n Runs L2 distance on the query and document embeddings\n\n **Usage:**\n ```\n # Below is just one example. See supported embedders: https://gpt-index.readthedocs.io/en/latest/core_modules/model_modules/embeddings/root.html\n from langchain.embeddings.openai import OpenAIEmbeddings\n\n model_name = 'text-embedding-ada-002'\n\n embed_model = OpenAIEmbeddings(\n model=model_name,\n openai_api_key=OPENAI_API_KEY\n )\n\n # Create the feedback function\n f_embed = feedback.Embeddings(embed_model=embed_model)\n f_embed_dist = feedback.Feedback(f_embed.euclidean_distance).on_input().on(Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content)\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Args:\n query (str): A text prompt to a vector DB. \n document (str): The document returned from the vector DB.\n\n Returns:\n - float: the embedding vector distance\n \"\"\"\n import sklearn\n query_embed = np.asarray(\n self._embed_model.get_query_embedding(query)\n ).reshape(\n 1, -1\n ) # sklearn expects 2d array (first dimension number of samples)\n document_embed = np.asarray(\n self._embed_model.get_text_embedding(document)\n ).reshape(\n 1, -1\n ) # sklearn expects 2d array (first dimension number of samples)\n\n return sklearn.metrics.pairwise.euclidean_distances(\n query_embed, document_embed\n )[0][\n 0\n ] # final results will be dimensions (sample query x sample doc) === (1,1)\n
"},{"location":"trulens_eval/api/feedback/#trulens_eval.trulens_eval.feedback.embeddings.Embeddings.manhattan_distance","title":"
manhattan_distance(query, document)","text":"
Runs L1 distance on the query and document embeddings
Usage:
# Below is just one example. See supported embedders: https://gpt-index.readthedocs.io/en/latest/core_modules/model_modules/embeddings/root.html\nfrom langchain.embeddings.openai import OpenAIEmbeddings\n\nmodel_name = 'text-embedding-ada-002'\n\nembed_model = OpenAIEmbeddings(\n model=model_name,\n openai_api_key=OPENAI_API_KEY\n)\n\n# Create the feedback function\nf_embed = feedback.Embeddings(embed_model=embed_model)\nf_embed_dist = feedback.Feedback(f_embed.manhattan_distance).on_input().on(Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content)\n
The
on(...) selector can be changed. See Feedback Function Guide : Selectors
Parameters:
Name Type Description Default
query str A text prompt to a vector DB.
required
document str The document returned from the vector DB.
required
Returns:
Type Description
Union[float, Tuple[float, Dict[str, str]]] - float: the embedding vector distance
Source code in
trulens_eval/trulens_eval/feedback/embeddings.py def manhattan_distance(\n self, query: str, document: str\n) -> Union[float, Tuple[float, Dict[str, str]]]:\n\"\"\"\n Runs L1 distance on the query and document embeddings\n\n **Usage:**\n ```\n # Below is just one example. See supported embedders: https://gpt-index.readthedocs.io/en/latest/core_modules/model_modules/embeddings/root.html\n from langchain.embeddings.openai import OpenAIEmbeddings\n\n model_name = 'text-embedding-ada-002'\n\n embed_model = OpenAIEmbeddings(\n model=model_name,\n openai_api_key=OPENAI_API_KEY\n )\n\n # Create the feedback function\n f_embed = feedback.Embeddings(embed_model=embed_model)\n f_embed_dist = feedback.Feedback(f_embed.manhattan_distance).on_input().on(Select.Record.app.combine_documents_chain._call.args.inputs.input_documents[:].page_content)\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Args:\n query (str): A text prompt to a vector DB. \n document (str): The document returned from the vector DB.\n\n Returns:\n - float: the embedding vector distance\n \"\"\"\n import sklearn\n query_embed = np.asarray(\n self._embed_model.get_query_embedding(query)\n ).reshape(\n 1, -1\n ) # sklearn expects 2d array (first dimension number of samples)\n document_embed = np.asarray(\n self._embed_model.get_text_embedding(document)\n ).reshape(\n 1, -1\n ) # sklearn expects 2d array (first dimension number of samples)\n\n return sklearn.metrics.pairwise.manhattan_distances(\n query_embed, document_embed\n )[0][\n 0\n ] # final results will be dimensions (sample query x sample doc) === (1,1)\n
"},{"location":"trulens_eval/api/huggingface_provider/","title":"LiteLLM APIs","text":"
Below is how you can instantiate HuggingFace as a provider, along with feedback functions available only from HuggingFace.
Bases: Provider
Out of the box feedback functions calling Huggingface APIs.
Source code in
trulens_eval/trulens_eval/feedback/provider/hugs.py class Huggingface(Provider):\n\"\"\"\n Out of the box feedback functions calling Huggingface APIs.\n \"\"\"\n\n endpoint: Endpoint\n\n def __init__(self, name: Optional[str] = None, endpoint=None, **kwargs):\n # NOTE(piotrm): pydantic adds endpoint to the signature of this\n # constructor if we don't include it explicitly, even though we set it\n # down below. Adding it as None here as a temporary hack.\n\"\"\"\n Create a Huggingface Provider with out of the box feedback functions.\n\n **Usage:**\n ```python\n from trulens_eval.feedback.provider.hugs import Huggingface\n huggingface_provider = Huggingface()\n ```\n\n Args:\n endpoint (Endpoint): Internal Usage for DB serialization\n \"\"\"\n\n kwargs['name'] = name\n\n self_kwargs = dict()\n\n # TODO: figure out why all of this logic is necessary:\n if endpoint is None:\n self_kwargs['endpoint'] = HuggingfaceEndpoint(**kwargs)\n else:\n if isinstance(endpoint, Endpoint):\n self_kwargs['endpoint'] = endpoint\n else:\n self_kwargs['endpoint'] = HuggingfaceEndpoint(**endpoint)\n\n self_kwargs['name'] = name or \"huggingface\"\n\n super().__init__(\n **self_kwargs\n ) # need to include pydantic.BaseModel.__init__\n\n # TODEP\n @_tci\n def language_match(self, text1: str, text2: str) -> Tuple[float, Dict]:\n\"\"\"\n Uses Huggingface's papluca/xlm-roberta-base-language-detection model. A\n function that uses language detection on `text1` and `text2` and\n calculates the probit difference on the language detected on text1. The\n function is: `1.0 - (|probit_language_text1(text1) -\n probit_language_text1(text2))`\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.hugs import Huggingface\n huggingface_provider = Huggingface()\n\n feedback = Feedback(huggingface_provider.language_match).on_input_output() \n ```\n The `on_input_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text1 (str): Text to evaluate.\n text2 (str): Comparative text to evaluate.\n\n Returns:\n\n float: A value between 0 and 1. 0 being \"different languages\" and 1\n being \"same languages\".\n \"\"\"\n\n def get_scores(text):\n payload = {\"inputs\": text}\n hf_response = self.endpoint.post(\n url=HUGS_LANGUAGE_API_URL, payload=payload, timeout=30\n )\n return {r['label']: r['score'] for r in hf_response}\n\n with ThreadPoolExecutor(max_workers=2) as tpool:\n max_length = 500\n f_scores1: Future[Dict] = tpool.submit(\n get_scores, text=text1[:max_length]\n )\n f_scores2: Future[Dict] = tpool.submit(\n get_scores, text=text2[:max_length]\n )\n\n wait([f_scores1, f_scores2])\n\n scores1: Dict = f_scores1.result()\n scores2: Dict = f_scores2.result()\n\n langs = list(scores1.keys())\n prob1 = np.array([scores1[k] for k in langs])\n prob2 = np.array([scores2[k] for k in langs])\n diff = prob1 - prob2\n\n l1: float = float(1.0 - (np.linalg.norm(diff, ord=1)) / 2.0)\n\n return l1, dict(text1_scores=scores1, text2_scores=scores2)\n\n # TODEP\n @_tci\n def positive_sentiment(self, text: str) -> float:\n\"\"\"\n Uses Huggingface's cardiffnlp/twitter-roberta-base-sentiment model. A\n function that uses a sentiment classifier on `text`.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.hugs import Huggingface\n huggingface_provider = Huggingface()\n\n feedback = Feedback(huggingface_provider.positive_sentiment).on_output() \n ```\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0 and 1. 0 being \"negative sentiment\" and 1\n being \"positive sentiment\".\n \"\"\"\n\n max_length = 500\n truncated_text = text[:max_length]\n payload = {\"inputs\": truncated_text}\n\n hf_response = self.endpoint.post(\n url=HUGS_SENTIMENT_API_URL, payload=payload\n )\n\n for label in hf_response:\n if label['label'] == 'LABEL_2':\n return float(label['score'])\n\n raise RuntimeError(\"LABEL_2 not found in huggingface api response.\")\n\n # TODEP\n @_tci\n def not_toxic(self, text: str) -> float:\n\"\"\"\n Uses Huggingface's martin-ha/toxic-comment-model model. A function that\n uses a toxic comment classifier on `text`.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.hugs import Huggingface\n huggingface_provider = Huggingface()\n\n feedback = Feedback(huggingface_provider.not_toxic).on_output() \n ```\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0 and 1. 0 being \"toxic\" and 1 being \"not\n toxic\".\n \"\"\"\n\n assert len(text) > 0, \"Input cannot be blank.\"\n\n max_length = 500\n truncated_text = text[:max_length]\n payload = {\"inputs\": truncated_text}\n hf_response = self.endpoint.post(\n url=HUGS_TOXIC_API_URL, payload=payload\n )\n\n for label in hf_response:\n if label['label'] == 'toxic':\n return label['score']\n\n raise RuntimeError(\"LABEL_2 not found in huggingface api response.\")\n\n # TODEP\n @_tci\n def _summarized_groundedness(self, premise: str, hypothesis: str) -> float:\n\"\"\" A groundedness measure best used for summarized premise against simple hypothesis.\n This Huggingface implementation uses NLI.\n\n Args:\n premise (str): NLI Premise\n hypothesis (str): NLI Hypothesis\n\n Returns:\n float: NLI Entailment\n \"\"\"\n\n if not '.' == premise[len(premise) - 1]:\n premise = premise + '.'\n nli_string = premise + ' ' + hypothesis\n payload = {\"inputs\": nli_string}\n hf_response = self.endpoint.post(url=HUGS_NLI_API_URL, payload=payload)\n\n for label in hf_response:\n if label['label'] == 'entailment':\n return label['score']\n\n raise RuntimeError(\"LABEL_2 not found in huggingface api response.\")\n\n # TODEP\n @_tci\n def _doc_groundedness(self, premise: str, hypothesis: str) -> float:\n\"\"\"\n A groundedness measure for full document premise against hypothesis.\n This Huggingface implementation uses DocNLI. The Hypoethsis still only\n works on single small hypothesis.\n\n Args:\n premise (str): NLI Premise\n hypothesis (str): NLI Hypothesis\n\n Returns:\n float: NLI Entailment\n \"\"\"\n nli_string = premise + ' [SEP] ' + hypothesis\n payload = {\"inputs\": nli_string}\n hf_response = self.endpoint.post(\n url=HUGS_DOCNLI_API_URL, payload=payload\n )\n\n for label in hf_response:\n if label['label'] == 'entailment':\n return label['score']\n\n def pii_detection(self, text: str) -> float:\n\"\"\"\n NER model to detect PII.\n **Usage:**\n ```\n hugs = Huggingface()\n\n # Define a pii_detection feedback function using HuggingFace.\n f_pii_detection = Feedback(hugs.pii_detection).on_input()\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Args:\n input (str): A text prompt that may contain a name.\n\n Returns:\n - float: the likelihood that a name is contained in the input text.\n \"\"\"\n\n # Initialize a list to store scores for \"NAME\" entities\n likelihood_scores = []\n\n payload = {\"inputs\": text}\n\n hf_response = self.endpoint.post(\n url=HUGS_PII_DETECTION_API_URL, payload=payload\n )\n\n # If the response is a dictionary, convert it to a list. This is for when only one name is identified.\n if isinstance(hf_response, dict):\n hf_response = [hf_response]\n\n if not isinstance(hf_response, list):\n raise ValueError(\n f\"Unexpected response from Huggingface API: {hf_response}\"\n )\n\n # Iterate through the entities and extract scores for \"NAME\" entities\n for entity in hf_response:\n likelihood_scores.append(entity[\"score\"])\n\n # Calculate the sum of all individual likelihood scores (P(A) + P(B) + ...)\n sum_individual_probabilities = sum(likelihood_scores)\n\n # Initialize the total likelihood for at least one name\n total_likelihood = sum_individual_probabilities\n\n # Calculate the product of pairwise likelihood scores (P(A and B), P(A and C), ...)\n for i in range(len(likelihood_scores)):\n for j in range(i + 1, len(likelihood_scores)):\n pairwise_likelihood = likelihood_scores[i] * likelihood_scores[j]\n total_likelihood -= pairwise_likelihood\n\n score = 1 - total_likelihood\n\n return score\n\n def pii_detection_with_cot_reasons(self, text: str):\n\"\"\"\n NER model to detect PII, with reasons.\n\n **Usage:**\n ```\n hugs = Huggingface()\n\n # Define a pii_detection feedback function using HuggingFace.\n f_pii_detection = Feedback(hugs.pii_detection).on_input()\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n \"\"\"\n\n # Initialize a dictionary to store reasons\n reasons = {}\n\n # Initialize a list to store scores for \"NAME\" entities\n likelihood_scores = []\n\n payload = {\"inputs\": text}\n\n try:\n hf_response = self.endpoint.post(\n url=HUGS_PII_DETECTION_API_URL, payload=payload\n )\n\n # TODO: Make error handling more granular so it's not swallowed.\n except Exception as e:\n logger.debug(\"No PII was found\")\n hf_response = [\n {\n \"entity_group\": \"NONE\",\n \"score\": 0.0,\n \"word\": np.nan,\n \"start\": np.nan,\n \"end\": np.nan\n }\n ]\n\n # Convert the response to a list if it's not already a list\n if not isinstance(hf_response, list):\n hf_response = [hf_response]\n\n # Check if the response is a list\n if not isinstance(hf_response, list):\n raise ValueError(\n \"Unexpected response from Huggingface API: response should be a list or a dictionary\"\n )\n\n # Iterate through the entities and extract \"word\" and \"score\" for \"NAME\" entities\n for i, entity in enumerate(hf_response):\n reasons[f\"{entity.get('entity_group')} detected: {entity['word']}\"\n ] = f\"PII Likelihood: {entity['score']}\"\n likelihood_scores.append(entity[\"score\"])\n\n # Calculate the sum of all individual likelihood scores (P(A) + P(B) + ...)\n sum_individual_probabilities = sum(likelihood_scores)\n\n # Initialize the total likelihood for at least one name\n total_likelihood = sum_individual_probabilities\n\n # Calculate the product of pairwise likelihood scores (P(A and B), P(A and C), ...)\n for i in range(len(likelihood_scores)):\n for j in range(i + 1, len(likelihood_scores)):\n pairwise_likelihood = likelihood_scores[i] * likelihood_scores[j]\n total_likelihood -= pairwise_likelihood\n\n score = 1 - total_likelihood\n\n return score, reasons\n
"},{"location":"trulens_eval/api/huggingface_provider/#trulens_eval.trulens_eval.feedback.provider.hugs.Huggingface.__init__","title":"
__init__(name=None, endpoint=None, **kwargs)","text":"
Create a Huggingface Provider with out of the box feedback functions.
Usage:
from trulens_eval.feedback.provider.hugs import Huggingface\nhuggingface_provider = Huggingface()\n
Parameters:
Name Type Description Default
endpoint Endpoint Internal Usage for DB serialization
None Source code in
trulens_eval/trulens_eval/feedback/provider/hugs.py def __init__(self, name: Optional[str] = None, endpoint=None, **kwargs):\n # NOTE(piotrm): pydantic adds endpoint to the signature of this\n # constructor if we don't include it explicitly, even though we set it\n # down below. Adding it as None here as a temporary hack.\n\"\"\"\n Create a Huggingface Provider with out of the box feedback functions.\n\n **Usage:**\n ```python\n from trulens_eval.feedback.provider.hugs import Huggingface\n huggingface_provider = Huggingface()\n ```\n\n Args:\n endpoint (Endpoint): Internal Usage for DB serialization\n \"\"\"\n\n kwargs['name'] = name\n\n self_kwargs = dict()\n\n # TODO: figure out why all of this logic is necessary:\n if endpoint is None:\n self_kwargs['endpoint'] = HuggingfaceEndpoint(**kwargs)\n else:\n if isinstance(endpoint, Endpoint):\n self_kwargs['endpoint'] = endpoint\n else:\n self_kwargs['endpoint'] = HuggingfaceEndpoint(**endpoint)\n\n self_kwargs['name'] = name or \"huggingface\"\n\n super().__init__(\n **self_kwargs\n ) # need to include pydantic.BaseModel.__init__\n
"},{"location":"trulens_eval/api/huggingface_provider/#trulens_eval.trulens_eval.feedback.provider.hugs.Huggingface.language_match","title":"
language_match(text1, text2)","text":"
Uses Huggingface's papluca/xlm-roberta-base-language-detection model. A function that uses language detection on text1 and text2 and calculates the probit difference on the language detected on text1. The function is: 1.0 - (|probit_language_text1(text1) - probit_language_text1(text2))
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback.provider.hugs import Huggingface\nhuggingface_provider = Huggingface()\n\nfeedback = Feedback(huggingface_provider.language_match).on_input_output() \n
The
on_input_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text1 str Text to evaluate.
required
text2 str Comparative text to evaluate.
required
Returns:
Name Type Description
float float A value between 0 and 1. 0 being \"different languages\" and 1
Dict being \"same languages\".
Source code in
trulens_eval/trulens_eval/feedback/provider/hugs.py @_tci\ndef language_match(self, text1: str, text2: str) -> Tuple[float, Dict]:\n\"\"\"\n Uses Huggingface's papluca/xlm-roberta-base-language-detection model. A\n function that uses language detection on `text1` and `text2` and\n calculates the probit difference on the language detected on text1. The\n function is: `1.0 - (|probit_language_text1(text1) -\n probit_language_text1(text2))`\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.hugs import Huggingface\n huggingface_provider = Huggingface()\n\n feedback = Feedback(huggingface_provider.language_match).on_input_output() \n ```\n The `on_input_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text1 (str): Text to evaluate.\n text2 (str): Comparative text to evaluate.\n\n Returns:\n\n float: A value between 0 and 1. 0 being \"different languages\" and 1\n being \"same languages\".\n \"\"\"\n\n def get_scores(text):\n payload = {\"inputs\": text}\n hf_response = self.endpoint.post(\n url=HUGS_LANGUAGE_API_URL, payload=payload, timeout=30\n )\n return {r['label']: r['score'] for r in hf_response}\n\n with ThreadPoolExecutor(max_workers=2) as tpool:\n max_length = 500\n f_scores1: Future[Dict] = tpool.submit(\n get_scores, text=text1[:max_length]\n )\n f_scores2: Future[Dict] = tpool.submit(\n get_scores, text=text2[:max_length]\n )\n\n wait([f_scores1, f_scores2])\n\n scores1: Dict = f_scores1.result()\n scores2: Dict = f_scores2.result()\n\n langs = list(scores1.keys())\n prob1 = np.array([scores1[k] for k in langs])\n prob2 = np.array([scores2[k] for k in langs])\n diff = prob1 - prob2\n\n l1: float = float(1.0 - (np.linalg.norm(diff, ord=1)) / 2.0)\n\n return l1, dict(text1_scores=scores1, text2_scores=scores2)\n
"},{"location":"trulens_eval/api/huggingface_provider/#trulens_eval.trulens_eval.feedback.provider.hugs.Huggingface.not_toxic","title":"
not_toxic(text)","text":"
Uses Huggingface's martin-ha/toxic-comment-model model. A function that uses a toxic comment classifier on text.
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback.provider.hugs import Huggingface\nhuggingface_provider = Huggingface()\n\nfeedback = Feedback(huggingface_provider.not_toxic).on_output() \n
The
on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str Text to evaluate.
required
Returns:
Name Type Description
float float A value between 0 and 1. 0 being \"toxic\" and 1 being \"not
float toxic\".
Source code in
trulens_eval/trulens_eval/feedback/provider/hugs.py @_tci\ndef not_toxic(self, text: str) -> float:\n\"\"\"\n Uses Huggingface's martin-ha/toxic-comment-model model. A function that\n uses a toxic comment classifier on `text`.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.hugs import Huggingface\n huggingface_provider = Huggingface()\n\n feedback = Feedback(huggingface_provider.not_toxic).on_output() \n ```\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0 and 1. 0 being \"toxic\" and 1 being \"not\n toxic\".\n \"\"\"\n\n assert len(text) > 0, \"Input cannot be blank.\"\n\n max_length = 500\n truncated_text = text[:max_length]\n payload = {\"inputs\": truncated_text}\n hf_response = self.endpoint.post(\n url=HUGS_TOXIC_API_URL, payload=payload\n )\n\n for label in hf_response:\n if label['label'] == 'toxic':\n return label['score']\n\n raise RuntimeError(\"LABEL_2 not found in huggingface api response.\")\n
"},{"location":"trulens_eval/api/huggingface_provider/#trulens_eval.trulens_eval.feedback.provider.hugs.Huggingface.pii_detection","title":"
pii_detection(text)","text":"
NER model to detect PII. Usage:
hugs = Huggingface()\n\n# Define a pii_detection feedback function using HuggingFace.\nf_pii_detection = Feedback(hugs.pii_detection).on_input()\n
The
on(...) selector can be changed. See Feedback Function Guide : Selectors
Parameters:
Name Type Description Default
input str A text prompt that may contain a name.
required
Returns:
Type Description
float - float: the likelihood that a name is contained in the input text.
Source code in
trulens_eval/trulens_eval/feedback/provider/hugs.py def pii_detection(self, text: str) -> float:\n\"\"\"\n NER model to detect PII.\n **Usage:**\n ```\n hugs = Huggingface()\n\n # Define a pii_detection feedback function using HuggingFace.\n f_pii_detection = Feedback(hugs.pii_detection).on_input()\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n\n Args:\n input (str): A text prompt that may contain a name.\n\n Returns:\n - float: the likelihood that a name is contained in the input text.\n \"\"\"\n\n # Initialize a list to store scores for \"NAME\" entities\n likelihood_scores = []\n\n payload = {\"inputs\": text}\n\n hf_response = self.endpoint.post(\n url=HUGS_PII_DETECTION_API_URL, payload=payload\n )\n\n # If the response is a dictionary, convert it to a list. This is for when only one name is identified.\n if isinstance(hf_response, dict):\n hf_response = [hf_response]\n\n if not isinstance(hf_response, list):\n raise ValueError(\n f\"Unexpected response from Huggingface API: {hf_response}\"\n )\n\n # Iterate through the entities and extract scores for \"NAME\" entities\n for entity in hf_response:\n likelihood_scores.append(entity[\"score\"])\n\n # Calculate the sum of all individual likelihood scores (P(A) + P(B) + ...)\n sum_individual_probabilities = sum(likelihood_scores)\n\n # Initialize the total likelihood for at least one name\n total_likelihood = sum_individual_probabilities\n\n # Calculate the product of pairwise likelihood scores (P(A and B), P(A and C), ...)\n for i in range(len(likelihood_scores)):\n for j in range(i + 1, len(likelihood_scores)):\n pairwise_likelihood = likelihood_scores[i] * likelihood_scores[j]\n total_likelihood -= pairwise_likelihood\n\n score = 1 - total_likelihood\n\n return score\n
"},{"location":"trulens_eval/api/huggingface_provider/#trulens_eval.trulens_eval.feedback.provider.hugs.Huggingface.pii_detection_with_cot_reasons","title":"
pii_detection_with_cot_reasons(text)","text":"
NER model to detect PII, with reasons.
Usage:
hugs = Huggingface()\n\n# Define a pii_detection feedback function using HuggingFace.\nf_pii_detection = Feedback(hugs.pii_detection).on_input()\n
The
on(...) selector can be changed. See Feedback Function Guide : Selectors Source code in
trulens_eval/trulens_eval/feedback/provider/hugs.py def pii_detection_with_cot_reasons(self, text: str):\n\"\"\"\n NER model to detect PII, with reasons.\n\n **Usage:**\n ```\n hugs = Huggingface()\n\n # Define a pii_detection feedback function using HuggingFace.\n f_pii_detection = Feedback(hugs.pii_detection).on_input()\n ```\n The `on(...)` selector can be changed. See [Feedback Function Guide : Selectors](https://www.trulens.org/trulens_eval/feedback_function_guide/#selector-details)\n \"\"\"\n\n # Initialize a dictionary to store reasons\n reasons = {}\n\n # Initialize a list to store scores for \"NAME\" entities\n likelihood_scores = []\n\n payload = {\"inputs\": text}\n\n try:\n hf_response = self.endpoint.post(\n url=HUGS_PII_DETECTION_API_URL, payload=payload\n )\n\n # TODO: Make error handling more granular so it's not swallowed.\n except Exception as e:\n logger.debug(\"No PII was found\")\n hf_response = [\n {\n \"entity_group\": \"NONE\",\n \"score\": 0.0,\n \"word\": np.nan,\n \"start\": np.nan,\n \"end\": np.nan\n }\n ]\n\n # Convert the response to a list if it's not already a list\n if not isinstance(hf_response, list):\n hf_response = [hf_response]\n\n # Check if the response is a list\n if not isinstance(hf_response, list):\n raise ValueError(\n \"Unexpected response from Huggingface API: response should be a list or a dictionary\"\n )\n\n # Iterate through the entities and extract \"word\" and \"score\" for \"NAME\" entities\n for i, entity in enumerate(hf_response):\n reasons[f\"{entity.get('entity_group')} detected: {entity['word']}\"\n ] = f\"PII Likelihood: {entity['score']}\"\n likelihood_scores.append(entity[\"score\"])\n\n # Calculate the sum of all individual likelihood scores (P(A) + P(B) + ...)\n sum_individual_probabilities = sum(likelihood_scores)\n\n # Initialize the total likelihood for at least one name\n total_likelihood = sum_individual_probabilities\n\n # Calculate the product of pairwise likelihood scores (P(A and B), P(A and C), ...)\n for i in range(len(likelihood_scores)):\n for j in range(i + 1, len(likelihood_scores)):\n pairwise_likelihood = likelihood_scores[i] * likelihood_scores[j]\n total_likelihood -= pairwise_likelihood\n\n score = 1 - total_likelihood\n\n return score, reasons\n
"},{"location":"trulens_eval/api/huggingface_provider/#trulens_eval.trulens_eval.feedback.provider.hugs.Huggingface.positive_sentiment","title":"
positive_sentiment(text)","text":"
Uses Huggingface's cardiffnlp/twitter-roberta-base-sentiment model. A function that uses a sentiment classifier on text.
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback.provider.hugs import Huggingface\nhuggingface_provider = Huggingface()\n\nfeedback = Feedback(huggingface_provider.positive_sentiment).on_output() \n
The
on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str Text to evaluate.
required
Returns:
Name Type Description
float float A value between 0 and 1. 0 being \"negative sentiment\" and 1
float being \"positive sentiment\".
Source code in
trulens_eval/trulens_eval/feedback/provider/hugs.py @_tci\ndef positive_sentiment(self, text: str) -> float:\n\"\"\"\n Uses Huggingface's cardiffnlp/twitter-roberta-base-sentiment model. A\n function that uses a sentiment classifier on `text`.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.hugs import Huggingface\n huggingface_provider = Huggingface()\n\n feedback = Feedback(huggingface_provider.positive_sentiment).on_output() \n ```\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0 and 1. 0 being \"negative sentiment\" and 1\n being \"positive sentiment\".\n \"\"\"\n\n max_length = 500\n truncated_text = text[:max_length]\n payload = {\"inputs\": truncated_text}\n\n hf_response = self.endpoint.post(\n url=HUGS_SENTIMENT_API_URL, payload=payload\n )\n\n for label in hf_response:\n if label['label'] == 'LABEL_2':\n return float(label['score'])\n\n raise RuntimeError(\"LABEL_2 not found in huggingface api response.\")\n
"},{"location":"trulens_eval/api/litellm_provider/","title":"LiteLLM APIs","text":"
Below is how you can instantiate LiteLLM as a provider. LiteLLM supports 100+ models from OpenAI, Cohere, Anthropic, HuggingFace, Meta and more. You can find more information about models available here.
All feedback functions listed in the base LLMProvider class can be run with LiteLLM.
Bases: LLMProvider
Out of the box feedback functions calling LiteLLM API.
Source code in
trulens_eval/trulens_eval/feedback/provider/litellm.py class LiteLLM(LLMProvider):\n\"\"\"Out of the box feedback functions calling LiteLLM API.\n \"\"\"\n model_engine: str\n endpoint: Endpoint\n\n def __init__(\n self, *args, endpoint=None, model_engine=\"gpt-3.5-turbo\", **kwargs\n ):\n # NOTE(piotrm): pydantic adds endpoint to the signature of this\n # constructor if we don't include it explicitly, even though we set it\n # down below. Adding it as None here as a temporary hack.\n\"\"\"\n Create an LiteLLM Provider with out of the box feedback functions.\n\n **Usage:**\n ```\n from trulens_eval.feedback.provider.litellm import LiteLLM\n litellm_provider = LiteLLM()\n\n ```\n\n Args:\n model_engine (str): The LiteLLM completion model.Defaults to `gpt-3.5-turbo`\n endpoint (Endpoint): Internal Usage for DB serialization\n \"\"\"\n # TODO: why was self_kwargs required here independently of kwargs?\n self_kwargs = dict()\n self_kwargs.update(**kwargs)\n self_kwargs['model_engine'] = model_engine\n self_kwargs['endpoint'] = LiteLLMEndpoint(*args, **kwargs)\n\n super().__init__(\n **self_kwargs\n ) # need to include pydantic.BaseModel.__init__\n\n def _create_chat_completion(\n self,\n prompt: Optional[str] = None,\n messages: Optional[Sequence[Dict]] = None,\n **kwargs\n ) -> str:\n\n from litellm import completion\n if prompt is not None:\n comp = completion(\n model=self.model_engine,\n messages=[{\n \"role\": \"system\",\n \"content\": prompt\n }],\n **kwargs\n )\n elif messages is not None:\n comp = completion(\n model=self.model_engine, messages=messages, **kwargs\n )\n\n else:\n raise ValueError(\"`prompt` or `messages` must be specified.\")\n\n assert isinstance(comp, dict)\n\n return comp[\"choices\"][0][\"message\"][\"content\"]\n
"},{"location":"trulens_eval/api/litellm_provider/#trulens_eval.trulens_eval.feedback.provider.litellm.LiteLLM.__init__","title":"
__init__(*args, endpoint=None, model_engine='gpt-3.5-turbo', **kwargs)","text":"
Create an LiteLLM Provider with out of the box feedback functions.
Usage:
from trulens_eval.feedback.provider.litellm import LiteLLM\nlitellm_provider = LiteLLM()\n
Parameters:
Name Type Description Default
model_engine str The LiteLLM completion model.Defaults to gpt-3.5-turbo
'gpt-3.5-turbo' endpoint Endpoint Internal Usage for DB serialization
None Source code in
trulens_eval/trulens_eval/feedback/provider/litellm.py def __init__(\n self, *args, endpoint=None, model_engine=\"gpt-3.5-turbo\", **kwargs\n):\n # NOTE(piotrm): pydantic adds endpoint to the signature of this\n # constructor if we don't include it explicitly, even though we set it\n # down below. Adding it as None here as a temporary hack.\n\"\"\"\n Create an LiteLLM Provider with out of the box feedback functions.\n\n **Usage:**\n ```\n from trulens_eval.feedback.provider.litellm import LiteLLM\n litellm_provider = LiteLLM()\n\n ```\n\n Args:\n model_engine (str): The LiteLLM completion model.Defaults to `gpt-3.5-turbo`\n endpoint (Endpoint): Internal Usage for DB serialization\n \"\"\"\n # TODO: why was self_kwargs required here independently of kwargs?\n self_kwargs = dict()\n self_kwargs.update(**kwargs)\n self_kwargs['model_engine'] = model_engine\n self_kwargs['endpoint'] = LiteLLMEndpoint(*args, **kwargs)\n\n super().__init__(\n **self_kwargs\n ) # need to include pydantic.BaseModel.__init__\n
"},{"location":"trulens_eval/api/openai_provider/","title":"OpenAI APIs","text":"
Below is how you can instantiate OpenAI as a provider, along with feedback functions available only from OpenAI.
Additionally, all feedback functions listed in the base LLMProvider class can be run with OpenAI.
Bases: LLMProvider
Out of the box feedback functions calling OpenAI APIs.
Source code in
trulens_eval/trulens_eval/feedback/provider/openai.py class OpenAI(LLMProvider):\n\"\"\"Out of the box feedback functions calling OpenAI APIs.\n \"\"\"\n # model_engine: str # LLMProvider\n\n endpoint: Endpoint\n\n def __init__(\n self, *args, endpoint=None, model_engine=\"gpt-3.5-turbo\", **kwargs\n ):\n # NOTE(piotrm): pydantic adds endpoint to the signature of this\n # constructor if we don't include it explicitly, even though we set it\n # down below. Adding it as None here as a temporary hack.\n\"\"\"\n Create an OpenAI Provider with out of the box feedback functions.\n\n **Usage:**\n ```python\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n ```\n\n Args:\n model_engine (str): The OpenAI completion model. Defaults to\n `gpt-3.5-turbo`\n endpoint (Endpoint): Internal Usage for DB serialization\n \"\"\"\n # TODO: why was self_kwargs required here independently of kwargs?\n self_kwargs = dict()\n self_kwargs.update(**kwargs)\n self_kwargs['model_engine'] = model_engine\n self_kwargs['endpoint'] = OpenAIEndpoint(*args, **kwargs)\n\n super().__init__(\n **self_kwargs\n ) # need to include pydantic.BaseModel.__init__\n\n # LLMProvider requirement\n def _create_chat_completion(\n self,\n prompt: Optional[str] = None,\n messages: Optional[Sequence[Dict]] = None,\n **kwargs\n ) -> str:\n\n if 'model' not in kwargs:\n kwargs['model'] = self.model_engine\n\n if 'temperature' not in kwargs:\n kwargs['temperature'] = 0.0\n\n if 'seed' not in kwargs:\n kwargs['seed'] = 123\n\n if prompt is not None:\n completion = self.endpoint.client.chat.completions.create(messages=[{\n \"role\": \"system\",\n \"content\": prompt\n }], **kwargs)\n elif messages is not None:\n completion = self.endpoint.client.chat.completions.create(messages=messages, **kwargs)\n\n else:\n raise ValueError(\"`prompt` or `messages` must be specified.\")\n\n return completion.choices[0].message.content\n\n def _moderation(self, text: str):\n # See https://platform.openai.com/docs/guides/moderation/overview .\n moderation_response = self.endpoint.run_me(\n lambda: self.endpoint.client.moderations.create(input=text)\n )\n return moderation_response.results[0]\n\n # TODEP\n def moderation_hate(self, text: str) -> float:\n\"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is hate\n speech.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_hate, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not hate) and 1.0 (hate).\n \"\"\"\n openai_response = self._moderation(text)\n return float(openai_response.category_scores.hate)\n\n # TODEP\n def moderation_hatethreatening(self, text: str) -> float:\n\"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is\n threatening speech.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_hatethreatening, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not threatening) and 1.0 (threatening).\n \"\"\"\n openai_response = self._moderation(text)\n\n return float(\n openai_response.category_scores.hate_threatening\n )\n\n # TODEP\n def moderation_selfharm(self, text: str) -> float:\n\"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is about\n self harm.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_selfharm, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not self harm) and 1.0 (self harm).\n \"\"\"\n openai_response = self._moderation(text)\n\n return float(\n openai_response.category_scores.self_harm\n )\n\n # TODEP\n def moderation_sexual(self, text: str) -> float:\n\"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is sexual\n speech.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_sexual, higher_is_better=False\n ).on_output()\n ```\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not sexual) and 1.0 (sexual).\n \"\"\"\n openai_response = self._moderation(text)\n\n return float(openai_response.category_scores.sexual)\n\n # TODEP\n def moderation_sexualminors(self, text: str) -> float:\n\"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is about\n sexual minors.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_sexualminors, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not sexual minors) and 1.0 (sexual\n minors).\n \"\"\"\n\n openai_response = self._moderation(text)\n\n return float(\n oopenai_response.category_scores.sexual_minors\n )\n\n # TODEP\n def moderation_violence(self, text: str) -> float:\n\"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is about\n violence.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_violence, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not violence) and 1.0 (violence).\n \"\"\"\n openai_response = self._moderation(text)\n\n return float(\n openai_response.category_scores.violence\n )\n\n # TODEP\n def moderation_violencegraphic(self, text: str) -> float:\n\"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is about\n graphic violence.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_violencegraphic, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not graphic violence) and 1.0 (graphic\n violence).\n \"\"\"\n openai_response = self._moderation(text)\n\n return float(\n openai_response.category_scores.violence_graphic\n )\n\n # TODEP\n def moderation_harassment(self, text: str) -> float:\n\"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is about\n graphic violence.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_harassment, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not harrassment) and 1.0 (harrassment).\n \"\"\"\n openai_response = self._moderation(text)\n\n return float(\n openai_response.category_scores.harassment\n )\n\n def moderation_harassment_threatening(self, text: str) -> float:\n\"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is about\n graphic violence.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_harassment_threatening, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not harrassment/threatening) and 1.0 (harrassment/threatening).\n \"\"\"\n openai_response = self._moderation(text)\n\n return float(\n openai_response.category_scores.harassment\n )\n
"},{"location":"trulens_eval/api/openai_provider/#trulens_eval.trulens_eval.feedback.provider.openai.OpenAI.__init__","title":"
__init__(*args, endpoint=None, model_engine='gpt-3.5-turbo', **kwargs)","text":"
Create an OpenAI Provider with out of the box feedback functions.
Usage:
from trulens_eval.feedback.provider.openai import OpenAI\nopenai_provider = OpenAI()\n
Parameters:
Name Type Description Default
model_engine str The OpenAI completion model. Defaults to gpt-3.5-turbo
'gpt-3.5-turbo' endpoint Endpoint Internal Usage for DB serialization
None Source code in
trulens_eval/trulens_eval/feedback/provider/openai.py def __init__(\n self, *args, endpoint=None, model_engine=\"gpt-3.5-turbo\", **kwargs\n):\n # NOTE(piotrm): pydantic adds endpoint to the signature of this\n # constructor if we don't include it explicitly, even though we set it\n # down below. Adding it as None here as a temporary hack.\n\"\"\"\n Create an OpenAI Provider with out of the box feedback functions.\n\n **Usage:**\n ```python\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n ```\n\n Args:\n model_engine (str): The OpenAI completion model. Defaults to\n `gpt-3.5-turbo`\n endpoint (Endpoint): Internal Usage for DB serialization\n \"\"\"\n # TODO: why was self_kwargs required here independently of kwargs?\n self_kwargs = dict()\n self_kwargs.update(**kwargs)\n self_kwargs['model_engine'] = model_engine\n self_kwargs['endpoint'] = OpenAIEndpoint(*args, **kwargs)\n\n super().__init__(\n **self_kwargs\n ) # need to include pydantic.BaseModel.__init__\n
"},{"location":"trulens_eval/api/openai_provider/#trulens_eval.trulens_eval.feedback.provider.openai.OpenAI.moderation_harassment","title":"
moderation_harassment(text)","text":"
Uses OpenAI's Moderation API. A function that checks if text is about graphic violence.
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback.provider.openai import OpenAI\nopenai_provider = OpenAI()\n\nfeedback = Feedback(\n openai_provider.moderation_harassment, higher_is_better=False\n).on_output()\n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str Text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not harrassment) and 1.0 (harrassment).
Source code in
trulens_eval/trulens_eval/feedback/provider/openai.py def moderation_harassment(self, text: str) -> float:\n\"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is about\n graphic violence.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_harassment, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not harrassment) and 1.0 (harrassment).\n \"\"\"\n openai_response = self._moderation(text)\n\n return float(\n openai_response.category_scores.harassment\n )\n
"},{"location":"trulens_eval/api/openai_provider/#trulens_eval.trulens_eval.feedback.provider.openai.OpenAI.moderation_harassment_threatening","title":"
moderation_harassment_threatening(text)","text":"
Uses OpenAI's Moderation API. A function that checks if text is about graphic violence.
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback.provider.openai import OpenAI\nopenai_provider = OpenAI()\n\nfeedback = Feedback(\n openai_provider.moderation_harassment_threatening, higher_is_better=False\n).on_output()\n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str Text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not harrassment/threatening) and 1.0 (harrassment/threatening).
Source code in
trulens_eval/trulens_eval/feedback/provider/openai.py def moderation_harassment_threatening(self, text: str) -> float:\n\"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is about\n graphic violence.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_harassment_threatening, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not harrassment/threatening) and 1.0 (harrassment/threatening).\n \"\"\"\n openai_response = self._moderation(text)\n\n return float(\n openai_response.category_scores.harassment\n )\n
"},{"location":"trulens_eval/api/openai_provider/#trulens_eval.trulens_eval.feedback.provider.openai.OpenAI.moderation_hate","title":"
moderation_hate(text)","text":"
Uses OpenAI's Moderation API. A function that checks if text is hate speech.
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback.provider.openai import OpenAI\nopenai_provider = OpenAI()\n\nfeedback = Feedback(\n openai_provider.moderation_hate, higher_is_better=False\n).on_output()\n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str Text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not hate) and 1.0 (hate).
Source code in
trulens_eval/trulens_eval/feedback/provider/openai.py def moderation_hate(self, text: str) -> float:\n\"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is hate\n speech.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_hate, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not hate) and 1.0 (hate).\n \"\"\"\n openai_response = self._moderation(text)\n return float(openai_response.category_scores.hate)\n
"},{"location":"trulens_eval/api/openai_provider/#trulens_eval.trulens_eval.feedback.provider.openai.OpenAI.moderation_hatethreatening","title":"
moderation_hatethreatening(text)","text":"
Uses OpenAI's Moderation API. A function that checks if text is threatening speech.
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback.provider.openai import OpenAI\nopenai_provider = OpenAI()\n\nfeedback = Feedback(\n openai_provider.moderation_hatethreatening, higher_is_better=False\n).on_output()\n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str Text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not threatening) and 1.0 (threatening).
Source code in
trulens_eval/trulens_eval/feedback/provider/openai.py def moderation_hatethreatening(self, text: str) -> float:\n\"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is\n threatening speech.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_hatethreatening, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not threatening) and 1.0 (threatening).\n \"\"\"\n openai_response = self._moderation(text)\n\n return float(\n openai_response.category_scores.hate_threatening\n )\n
"},{"location":"trulens_eval/api/openai_provider/#trulens_eval.trulens_eval.feedback.provider.openai.OpenAI.moderation_selfharm","title":"
moderation_selfharm(text)","text":"
Uses OpenAI's Moderation API. A function that checks if text is about self harm.
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback.provider.openai import OpenAI\nopenai_provider = OpenAI()\n\nfeedback = Feedback(\n openai_provider.moderation_selfharm, higher_is_better=False\n).on_output()\n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str Text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not self harm) and 1.0 (self harm).
Source code in
trulens_eval/trulens_eval/feedback/provider/openai.py def moderation_selfharm(self, text: str) -> float:\n\"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is about\n self harm.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_selfharm, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not self harm) and 1.0 (self harm).\n \"\"\"\n openai_response = self._moderation(text)\n\n return float(\n openai_response.category_scores.self_harm\n )\n
"},{"location":"trulens_eval/api/openai_provider/#trulens_eval.trulens_eval.feedback.provider.openai.OpenAI.moderation_sexual","title":"
moderation_sexual(text)","text":"
Uses OpenAI's Moderation API. A function that checks if text is sexual speech.
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback.provider.openai import OpenAI\nopenai_provider = OpenAI()\n\nfeedback = Feedback(\n openai_provider.moderation_sexual, higher_is_better=False\n).on_output()\n
The
on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str Text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not sexual) and 1.0 (sexual).
Source code in
trulens_eval/trulens_eval/feedback/provider/openai.py def moderation_sexual(self, text: str) -> float:\n\"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is sexual\n speech.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_sexual, higher_is_better=False\n ).on_output()\n ```\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not sexual) and 1.0 (sexual).\n \"\"\"\n openai_response = self._moderation(text)\n\n return float(openai_response.category_scores.sexual)\n
"},{"location":"trulens_eval/api/openai_provider/#trulens_eval.trulens_eval.feedback.provider.openai.OpenAI.moderation_sexualminors","title":"
moderation_sexualminors(text)","text":"
Uses OpenAI's Moderation API. A function that checks if text is about sexual minors.
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback.provider.openai import OpenAI\nopenai_provider = OpenAI()\n\nfeedback = Feedback(\n openai_provider.moderation_sexualminors, higher_is_better=False\n).on_output()\n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str Text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not sexual minors) and 1.0 (sexual
float minors).
Source code in
trulens_eval/trulens_eval/feedback/provider/openai.py def moderation_sexualminors(self, text: str) -> float:\n\"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is about\n sexual minors.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_sexualminors, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not sexual minors) and 1.0 (sexual\n minors).\n \"\"\"\n\n openai_response = self._moderation(text)\n\n return float(\n oopenai_response.category_scores.sexual_minors\n )\n
"},{"location":"trulens_eval/api/openai_provider/#trulens_eval.trulens_eval.feedback.provider.openai.OpenAI.moderation_violence","title":"
moderation_violence(text)","text":"
Uses OpenAI's Moderation API. A function that checks if text is about violence.
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback.provider.openai import OpenAI\nopenai_provider = OpenAI()\n\nfeedback = Feedback(\n openai_provider.moderation_violence, higher_is_better=False\n).on_output()\n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str Text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not violence) and 1.0 (violence).
Source code in
trulens_eval/trulens_eval/feedback/provider/openai.py def moderation_violence(self, text: str) -> float:\n\"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is about\n violence.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_violence, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not violence) and 1.0 (violence).\n \"\"\"\n openai_response = self._moderation(text)\n\n return float(\n openai_response.category_scores.violence\n )\n
"},{"location":"trulens_eval/api/openai_provider/#trulens_eval.trulens_eval.feedback.provider.openai.OpenAI.moderation_violencegraphic","title":"
moderation_violencegraphic(text)","text":"
Uses OpenAI's Moderation API. A function that checks if text is about graphic violence.
Usage:
from trulens_eval import Feedback\nfrom trulens_eval.feedback.provider.openai import OpenAI\nopenai_provider = OpenAI()\n\nfeedback = Feedback(\n openai_provider.moderation_violencegraphic, higher_is_better=False\n).on_output()\n
The on_output() selector can be changed. See Feedback Function Guide
Parameters:
Name Type Description Default
text str Text to evaluate.
required
Returns:
Name Type Description
float float A value between 0.0 (not graphic violence) and 1.0 (graphic
float violence).
Source code in
trulens_eval/trulens_eval/feedback/provider/openai.py def moderation_violencegraphic(self, text: str) -> float:\n\"\"\"\n Uses OpenAI's Moderation API. A function that checks if text is about\n graphic violence.\n\n **Usage:**\n ```python\n from trulens_eval import Feedback\n from trulens_eval.feedback.provider.openai import OpenAI\n openai_provider = OpenAI()\n\n feedback = Feedback(\n openai_provider.moderation_violencegraphic, higher_is_better=False\n ).on_output()\n ```\n\n The `on_output()` selector can be changed. See [Feedback Function\n Guide](https://www.trulens.org/trulens_eval/feedback_function_guide/)\n\n Args:\n text (str): Text to evaluate.\n\n Returns:\n float: A value between 0.0 (not graphic violence) and 1.0 (graphic\n violence).\n \"\"\"\n openai_response = self._moderation(text)\n\n return float(\n openai_response.category_scores.violence_graphic\n )\n
"},{"location":"trulens_eval/api/tru/","title":"Tru","text":"
Bases: SingletonPerName
Tru is the main class that provides an entry points to trulens-eval. Tru lets you:
- Log app prompts and outputs
- Log app Metadata
- Run and log feedback functions
- Run streamlit dashboard to view experiment results
By default, all data is logged to the current working directory to default.sqlite. Data can be logged to a SQLAlchemy-compatible referred to by database_url.
Source code in
trulens_eval/trulens_eval/tru.py class Tru(SingletonPerName):\n\"\"\"\n Tru is the main class that provides an entry points to trulens-eval. Tru lets you:\n\n * Log app prompts and outputs\n * Log app Metadata\n * Run and log feedback functions\n * Run streamlit dashboard to view experiment results\n\n By default, all data is logged to the current working directory to `default.sqlite`. \n Data can be logged to a SQLAlchemy-compatible referred to by `database_url`.\n \"\"\"\n DEFAULT_DATABASE_FILE = \"default.sqlite\"\n\n # Process or Thread of the deferred feedback function evaluator.\n evaluator_proc = None\n\n # Process of the dashboard app.\n dashboard_proc = None\n\n def Chain(self, chain, **kwargs):\n\"\"\"\n Create a TruChain with database managed by self.\n \"\"\"\n\n from trulens_eval.tru_chain import TruChain\n\n return TruChain(tru=self, app=chain, **kwargs)\n\n def Llama(self, engine, **kwargs):\n\"\"\"\n Create a llama_index engine with database managed by self.\n \"\"\"\n\n from trulens_eval.tru_llama import TruLlama\n\n return TruLlama(tru=self, app=engine, **kwargs)\n\n def Basic(self, text_to_text, **kwargs):\n from trulens_eval.tru_basic_app import TruBasicApp\n\n return TruBasicApp(tru=self, text_to_text=text_to_text, **kwargs)\n\n def Custom(self, app, **kwargs):\n from trulens_eval.tru_custom_app import TruCustomApp\n\n return TruCustomApp(tru=self, app=app, **kwargs)\n\n def __init__(\n self,\n database_url: Optional[str] = None,\n database_file: Optional[str] = None,\n database_redact_keys: bool = False\n ):\n\"\"\"\n TruLens instrumentation, logging, and feedback functions for apps.\n\n Args:\n database_url: SQLAlchemy database URL. Defaults to a local\n SQLite database file at 'default.sqlite'\n See [this article](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls)\n on SQLAlchemy database URLs.\n database_file: (Deprecated) Path to a local SQLite database file\n database_redact_keys: whether to redact secret keys in data to be written to database.\n \"\"\"\n if safe_hasattr(self, \"db\"):\n if database_url is not None or database_file is not None:\n logger.warning(\n f\"Tru was already initialized. Cannot change database_url={database_url} or database_file={database_file} .\"\n )\n\n # Already initialized by SingletonByName mechanism.\n return\n\n assert None in (database_url, database_file), \\\n \"Please specify at most one of `database_url` and `database_file`\"\n\n if database_file:\n warnings.warn(\n \"`database_file` is deprecated, use `database_url` instead as in `database_url='sqlite:///filename'.\",\n DeprecationWarning,\n stacklevel=2\n )\n\n if database_url is None:\n database_url = f\"sqlite:///{database_file or self.DEFAULT_DATABASE_FILE}\"\n\n self.db: SqlAlchemyDB = SqlAlchemyDB.from_db_url(\n database_url, redact_keys=database_redact_keys\n )\n\n print(\n f\"{UNICODE_SQUID} Tru initialized with db url {self.db.engine.url} .\"\n )\n if database_redact_keys:\n print(\n f\"{UNICODE_LOCK} Secret keys will not be included in the database.\"\n )\n else:\n print(\n f\"{UNICODE_STOP} Secret keys may be written to the database. \"\n \"See the `database_redact_keys` option of `Tru` to prevent this.\"\n )\n\n def reset_database(self):\n\"\"\"\n Reset the database. Clears all tables.\n \"\"\"\n\n self.db.reset_database()\n\n def migrate_database(self):\n\"\"\"\n Migrates the database. This should be run whenever there are breaking\n changes in a database created with an older version of trulens_eval.\n \"\"\"\n\n self.db.migrate_database()\n\n def add_record(self, record: Optional[Record] = None, **kwargs):\n\"\"\"\n Add a record to the database.\n\n Args:\n\n record: Record\n\n **kwargs: Record fields.\n\n Returns:\n RecordID: Unique record identifier.\n\n \"\"\"\n\n if record is None:\n record = Record(**kwargs)\n else:\n record.update(**kwargs)\n\n return self.db.insert_record(record=record)\n\n update_record = add_record\n\n def _submit_feedback_functions(\n self,\n record: Record,\n feedback_functions: Sequence[Feedback],\n app: Optional[AppDefinition] = None,\n on_done: Optional[Callable[['Future[Tuple[Feedback,FeedbackResult]]'],\n None]] = None\n ) -> List['Future[Tuple[Feedback,FeedbackResult]]']:\n app_id = record.app_id\n\n self.db: DB\n\n if app is None:\n app = AppDefinition.parse_obj(self.db.get_app(app_id=app_id))\n if app is None:\n raise RuntimeError(\n \"App {app_id} not present in db. \"\n \"Either add it with `tru.add_app` or provide `app_json` to `tru.run_feedback_functions`.\"\n )\n\n else:\n assert app_id == app.app_id, \"Record was produced by a different app.\"\n\n if self.db.get_app(app_id=app.app_id) is None:\n logger.warning(\n \"App {app_id} was not present in database. Adding it.\"\n )\n self.add_app(app=app)\n\n futures = []\n\n tp: TP = TP()\n\n for ffunc in feedback_functions:\n fut: 'Future[Tuple[Feedback,FeedbackResult]]' = \\\n tp.submit(lambda f: (f, f.run(app=app, record=record)), ffunc)\n\n if on_done is not None:\n fut.add_done_callback(on_done)\n\n futures.append(fut)\n\n return futures\n\n def run_feedback_functions(\n self,\n record: Record,\n feedback_functions: Sequence[Feedback],\n app: Optional[AppDefinition] = None,\n ) -> Iterable[FeedbackResult]:\n\"\"\"\n Run a collection of feedback functions and report their result.\n\n Parameters:\n\n record (Record): The record on which to evaluate the feedback\n functions.\n\n app (App, optional): The app that produced the given record.\n If not provided, it is looked up from the given database `db`.\n\n feedback_functions (Sequence[Feedback]): A collection of feedback\n functions to evaluate.\n\n Yields `FeedbackResult`, one for each element of `feedback_functions`\n potentially in random order.\n \"\"\"\n\n for res in as_completed(self._submit_feedback_functions(\n record=record, feedback_functions=feedback_functions, app=app)):\n\n yield res.result()[1]\n\n def add_app(self, app: AppDefinition) -> None:\n\"\"\"\n Add a app to the database. \n \"\"\"\n\n self.db.insert_app(app=app)\n\n def add_feedback(\n self, feedback_result: FeedbackResult = None, **kwargs\n ) -> None:\n\"\"\"\n Add a single feedback result to the database.\n \"\"\"\n\n if feedback_result is None:\n feedback_result = FeedbackResult(**kwargs)\n else:\n feedback_result.update(**kwargs)\n\n self.db.insert_feedback(feedback_result=feedback_result)\n\n def add_feedbacks(self, feedback_results: Iterable[FeedbackResult]) -> None:\n\"\"\"\n Add multiple feedback results to the database.\n \"\"\"\n\n for feedback_result in feedback_results:\n self.add_feedback(feedback_result=feedback_result)\n\n def get_app(self, app_id: Optional[str] = None) -> JSON:\n\"\"\"\n Look up a app from the database.\n \"\"\"\n\n return self.db.get_app(app_id)\n\n def get_apps(self) -> Iterable[JSON]:\n\"\"\"\n Look up all apps from the database.\n \"\"\"\n\n return self.db.get_apps()\n\n def get_records_and_feedback(self, app_ids: List[str]):\n\"\"\"\n Get records, their feeback results, and feedback names from the\n database. Pass an empty list of app_ids to return all.\n\n ```python\n tru.get_records_and_feedback(app_ids=[])\n ```\n \"\"\"\n\n df, feedback_columns = self.db.get_records_and_feedback(app_ids)\n\n return df, feedback_columns\n\n def get_leaderboard(self, app_ids: List[str]):\n\"\"\"\n Get a leaderboard by app id from the\n database. Pass an empty list of app_ids to return all.\n\n ```python\n tru.get_leaderboard(app_ids=[])\n ```\n \"\"\"\n df, feedback_cols = self.db.get_records_and_feedback(app_ids)\n\n col_agg_list = feedback_cols + ['latency', 'total_cost']\n\n leaderboard = df.groupby('app_id')[col_agg_list].mean().sort_values(\n by=feedback_cols, ascending=False\n )\n\n return leaderboard\n\n def start_evaluator(self,\n restart=False,\n fork=False) -> Union[Process, Thread]:\n\"\"\"\n Start a deferred feedback function evaluation thread.\n \"\"\"\n\n assert not fork, \"Fork mode not yet implemented.\"\n\n if self.evaluator_proc is not None:\n if restart:\n self.stop_evaluator()\n else:\n raise RuntimeError(\n \"Evaluator is already running in this process.\"\n )\n\n if not fork:\n self.evaluator_stop = threading.Event()\n\n def runloop():\n assert self.evaluator_stop is not None\n\n while fork or not self.evaluator_stop.is_set():\n futures = Feedback.evaluate_deferred(tru=self)\n\n if len(futures) > 0:\n print(\n f\"{UNICODE_YIELD}{UNICODE_YIELD}{UNICODE_YIELD} Started {len(futures)} deferred feedback functions.\"\n )\n wait(futures)\n print(\n f\"{UNICODE_CHECK}{UNICODE_CHECK}{UNICODE_CHECK} Finished evaluating deferred feedback functions.\"\n )\n\n if fork:\n sleep(10)\n else:\n self.evaluator_stop.wait(10)\n\n print(\"Evaluator stopped.\")\n\n if fork:\n proc = Process(target=runloop)\n else:\n proc = Thread(target=runloop)\n proc.daemon = True\n\n # Start a persistent thread or process that evaluates feedback functions.\n\n self.evaluator_proc = proc\n proc.start()\n\n return proc\n\n def stop_evaluator(self):\n\"\"\"\n Stop the deferred feedback evaluation thread.\n \"\"\"\n\n if self.evaluator_proc is None:\n raise RuntimeError(\"Evaluator not running this process.\")\n\n if isinstance(self.evaluator_proc, Process):\n self.evaluator_proc.terminate()\n\n elif isinstance(self.evaluator_proc, Thread):\n self.evaluator_stop.set()\n self.evaluator_proc.join()\n self.evaluator_stop = None\n\n self.evaluator_proc = None\n\n def stop_dashboard(self, force: bool = False) -> None:\n\"\"\"\n Stop existing dashboard(s) if running.\n\n Args:\n\n - force: bool: Also try to find any other dashboard processes not\n started in this notebook and shut them down too.\n\n Raises:\n\n - ValueError: Dashboard is not running.\n \"\"\"\n if Tru.dashboard_proc is None:\n if not force:\n raise ValueError(\n \"Dashboard not running in this workspace. \"\n \"You may be able to shut other instances by setting the `force` flag.\"\n )\n\n else:\n if sys.platform.startswith(\"win\"):\n raise RuntimeError(\n \"Force stop option is not supported on windows.\"\n )\n\n print(\"Force stopping dashboard ...\")\n import os\n import pwd # PROBLEM: does not exist on windows\n\n import psutil\n username = pwd.getpwuid(os.getuid())[0]\n for p in psutil.process_iter():\n try:\n cmd = \" \".join(p.cmdline())\n if \"streamlit\" in cmd and \"Leaderboard.py\" in cmd and p.username(\n ) == username:\n print(f\"killing {p}\")\n p.kill()\n except Exception as e:\n continue\n\n else:\n Tru.dashboard_proc.kill()\n Tru.dashboard_proc = None\n\n def run_dashboard_in_jupyter(self):\n\"\"\"\n Experimental approach to attempt to display the dashboard inside a\n jupyter notebook. Relies on the `streamlit_jupyter` package.\n \"\"\"\n # EXPERIMENTAL\n # TODO: check for jupyter\n\n logger.warning(\n \"Running dashboard inside a notebook is an experimental feature and may not work well.\"\n )\n\n from streamlit_jupyter import StreamlitPatcher\n StreamlitPatcher().jupyter()\n from trulens_eval import Leaderboard\n\n Leaderboard.main()\n\n def run_dashboard(\n self, force: bool = False, _dev: Optional[Path] = None\n ) -> Process:\n\"\"\"\n Run a streamlit dashboard to view logged results and apps.\n\n Args:\n\n - force: bool: Stop existing dashboard(s) first.\n\n - _dev: Optional[Path]: If given, run dashboard with the given\n PYTHONPATH. This can be used to run the dashboard from outside of\n its pip package installation folder.\n\n Raises:\n\n - ValueError: Dashboard is already running.\n\n Returns:\n\n - Process: Process containing streamlit dashboard.\n \"\"\"\n\n if force:\n self.stop_dashboard(force=force)\n\n print(\"Starting dashboard ...\")\n\n # Create .streamlit directory if it doesn't exist\n streamlit_dir = os.path.join(os.getcwd(), '.streamlit')\n os.makedirs(streamlit_dir, exist_ok=True)\n\n # Create config.toml file path\n config_path = os.path.join(streamlit_dir, 'config.toml')\n\n # Check if the file already exists\n if not os.path.exists(config_path):\n with open(config_path, 'w') as f:\n f.write('[theme]\\n')\n f.write('primaryColor=\"#0A2C37\"\\n')\n f.write('backgroundColor=\"#FFFFFF\"\\n')\n f.write('secondaryBackgroundColor=\"F5F5F5\"\\n')\n f.write('textColor=\"#0A2C37\"\\n')\n f.write('font=\"sans serif\"\\n')\n else:\n print(\"Config file already exists. Skipping writing process.\")\n\n # Create credentials.toml file path\n cred_path = os.path.join(streamlit_dir, 'credentials.toml')\n\n # Check if the file already exists\n if not os.path.exists(cred_path):\n with open(cred_path, 'w') as f:\n f.write('[general]\\n')\n f.write('email=\"\"\\n')\n else:\n print(\"Credentials file already exists. Skipping writing process.\")\n\n #run leaderboard with subprocess\n leaderboard_path = pkg_resources.resource_filename(\n 'trulens_eval', 'Leaderboard.py'\n )\n\n if Tru.dashboard_proc is not None:\n print(\"Dashboard already running at path:\", Tru.dashboard_urls)\n return Tru.dashboard_proc\n\n env_opts = {}\n if _dev is not None:\n env_opts['env'] = os.environ\n env_opts['env']['PYTHONPATH'] = str(_dev)\n\n proc = subprocess.Popen(\n [\n \"streamlit\", \"run\", \"--server.headless=True\", leaderboard_path,\n \"--\", \"--database-url\",\n self.db.engine.url.render_as_string(hide_password=False)\n ],\n stdout=subprocess.PIPE,\n stderr=subprocess.PIPE,\n text=True,\n **env_opts\n )\n\n started = threading.Event()\n tunnel_started = threading.Event()\n if is_notebook():\n out_stdout, out_stderr = setup_widget_stdout_stderr()\n else:\n out_stdout = None\n out_stderr = None\n\n IN_COLAB = 'google.colab' in sys.modules\n if IN_COLAB:\n tunnel_proc = subprocess.Popen(\n [\"npx\", \"localtunnel\", \"--port\", \"8501\"],\n stdout=subprocess.PIPE,\n stderr=subprocess.PIPE,\n text=True,\n **env_opts\n )\n\n def listen_to_tunnel(proc: subprocess.Popen, pipe, out, started):\n while proc.poll() is None:\n\n line = pipe.readline()\n if \"url\" in line:\n started.set()\n line = \"Go to this url and submit the ip given here. \" + line\n\n if out is not None:\n out.append_stdout(line)\n\n else:\n print(line)\n\n Tru.tunnel_listener_stdout = Thread(\n target=listen_to_tunnel,\n args=(\n tunnel_proc, tunnel_proc.stdout, out_stdout, tunnel_started\n )\n )\n Tru.tunnel_listener_stderr = Thread(\n target=listen_to_tunnel,\n args=(\n tunnel_proc, tunnel_proc.stderr, out_stderr, tunnel_started\n )\n )\n Tru.tunnel_listener_stdout.daemon = True\n Tru.tunnel_listener_stderr.daemon = True\n Tru.tunnel_listener_stdout.start()\n Tru.tunnel_listener_stderr.start()\n if not tunnel_started.wait(timeout=DASHBOARD_START_TIMEOUT\n ): # This might not work on windows.\n raise RuntimeError(\"Tunnel failed to start in time. \")\n\n def listen_to_dashboard(proc: subprocess.Popen, pipe, out, started):\n while proc.poll() is None:\n line = pipe.readline()\n if IN_COLAB:\n if \"External URL: \" in line:\n started.set()\n line = line.replace(\n \"External URL: http://\", \"Submit this IP Address: \"\n )\n line = line.replace(\":8501\", \"\")\n if out is not None:\n out.append_stdout(line)\n else:\n print(line)\n Tru.dashboard_urls = line # store the url when dashboard is started\n else:\n if \"Network URL: \" in line:\n url = line.split(\": \")[1]\n url = url.rstrip()\n print(f\"Dashboard started at {url} .\")\n started.set()\n Tru.dashboard_urls = line # store the url when dashboard is started\n if out is not None:\n out.append_stdout(line)\n else:\n print(line)\n if out is not None:\n out.append_stdout(\"Dashboard closed.\")\n else:\n print(\"Dashboard closed.\")\n\n Tru.dashboard_listener_stdout = Thread(\n target=listen_to_dashboard,\n args=(proc, proc.stdout, out_stdout, started)\n )\n Tru.dashboard_listener_stderr = Thread(\n target=listen_to_dashboard,\n args=(proc, proc.stderr, out_stderr, started)\n )\n\n # Purposely block main process from ending and wait for dashboard.\n Tru.dashboard_listener_stdout.daemon = False\n Tru.dashboard_listener_stderr.daemon = False\n\n Tru.dashboard_listener_stdout.start()\n Tru.dashboard_listener_stderr.start()\n\n Tru.dashboard_proc = proc\n\n wait_period = DASHBOARD_START_TIMEOUT\n if IN_COLAB:\n # Need more time to setup 2 processes tunnel and dashboard\n wait_period = wait_period * 3\n if not started.wait(timeout=wait_period\n ): # This might not work on windows.\n raise RuntimeError(\n \"Dashboard failed to start in time. \"\n \"Please inspect dashboard logs for additional information.\"\n )\n\n return proc\n\n start_dashboard = run_dashboard\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.Chain","title":"
Chain(chain, **kwargs)","text":"
Create a TruChain with database managed by self.
Source code in
trulens_eval/trulens_eval/tru.py def Chain(self, chain, **kwargs):\n\"\"\"\n Create a TruChain with database managed by self.\n \"\"\"\n\n from trulens_eval.tru_chain import TruChain\n\n return TruChain(tru=self, app=chain, **kwargs)\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.Llama","title":"
Llama(engine, **kwargs)","text":"
Create a llama_index engine with database managed by self.
Source code in
trulens_eval/trulens_eval/tru.py def Llama(self, engine, **kwargs):\n\"\"\"\n Create a llama_index engine with database managed by self.\n \"\"\"\n\n from trulens_eval.tru_llama import TruLlama\n\n return TruLlama(tru=self, app=engine, **kwargs)\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.__init__","title":"
__init__(database_url=None, database_file=None, database_redact_keys=False)","text":"
TruLens instrumentation, logging, and feedback functions for apps.
Parameters:
Name Type Description Default
database_url Optional[str] SQLAlchemy database URL. Defaults to a local SQLite database file at 'default.sqlite' See this article on SQLAlchemy database URLs.
None database_file Optional[str] (Deprecated) Path to a local SQLite database file
None database_redact_keys bool whether to redact secret keys in data to be written to database.
False Source code in
trulens_eval/trulens_eval/tru.py def __init__(\n self,\n database_url: Optional[str] = None,\n database_file: Optional[str] = None,\n database_redact_keys: bool = False\n):\n\"\"\"\n TruLens instrumentation, logging, and feedback functions for apps.\n\n Args:\n database_url: SQLAlchemy database URL. Defaults to a local\n SQLite database file at 'default.sqlite'\n See [this article](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls)\n on SQLAlchemy database URLs.\n database_file: (Deprecated) Path to a local SQLite database file\n database_redact_keys: whether to redact secret keys in data to be written to database.\n \"\"\"\n if safe_hasattr(self, \"db\"):\n if database_url is not None or database_file is not None:\n logger.warning(\n f\"Tru was already initialized. Cannot change database_url={database_url} or database_file={database_file} .\"\n )\n\n # Already initialized by SingletonByName mechanism.\n return\n\n assert None in (database_url, database_file), \\\n \"Please specify at most one of `database_url` and `database_file`\"\n\n if database_file:\n warnings.warn(\n \"`database_file` is deprecated, use `database_url` instead as in `database_url='sqlite:///filename'.\",\n DeprecationWarning,\n stacklevel=2\n )\n\n if database_url is None:\n database_url = f\"sqlite:///{database_file or self.DEFAULT_DATABASE_FILE}\"\n\n self.db: SqlAlchemyDB = SqlAlchemyDB.from_db_url(\n database_url, redact_keys=database_redact_keys\n )\n\n print(\n f\"{UNICODE_SQUID} Tru initialized with db url {self.db.engine.url} .\"\n )\n if database_redact_keys:\n print(\n f\"{UNICODE_LOCK} Secret keys will not be included in the database.\"\n )\n else:\n print(\n f\"{UNICODE_STOP} Secret keys may be written to the database. \"\n \"See the `database_redact_keys` option of `Tru` to prevent this.\"\n )\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.add_app","title":"
add_app(app)","text":"
Add a app to the database.
Source code in
trulens_eval/trulens_eval/tru.py def add_app(self, app: AppDefinition) -> None:\n\"\"\"\n Add a app to the database. \n \"\"\"\n\n self.db.insert_app(app=app)\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.add_feedback","title":"
add_feedback(feedback_result=None, **kwargs)","text":"
Add a single feedback result to the database.
Source code in
trulens_eval/trulens_eval/tru.py def add_feedback(\n self, feedback_result: FeedbackResult = None, **kwargs\n) -> None:\n\"\"\"\n Add a single feedback result to the database.\n \"\"\"\n\n if feedback_result is None:\n feedback_result = FeedbackResult(**kwargs)\n else:\n feedback_result.update(**kwargs)\n\n self.db.insert_feedback(feedback_result=feedback_result)\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.add_feedbacks","title":"
add_feedbacks(feedback_results)","text":"
Add multiple feedback results to the database.
Source code in
trulens_eval/trulens_eval/tru.py def add_feedbacks(self, feedback_results: Iterable[FeedbackResult]) -> None:\n\"\"\"\n Add multiple feedback results to the database.\n \"\"\"\n\n for feedback_result in feedback_results:\n self.add_feedback(feedback_result=feedback_result)\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.add_record","title":"
add_record(record=None, **kwargs)","text":"
Add a record to the database.
Parameters:
Name Type Description Default
record Optional[Record] Record
None **kwargs Record fields.
{} Returns:
Name Type Description
RecordID Unique record identifier.
Source code in
trulens_eval/trulens_eval/tru.py def add_record(self, record: Optional[Record] = None, **kwargs):\n\"\"\"\n Add a record to the database.\n\n Args:\n\n record: Record\n\n **kwargs: Record fields.\n\n Returns:\n RecordID: Unique record identifier.\n\n \"\"\"\n\n if record is None:\n record = Record(**kwargs)\n else:\n record.update(**kwargs)\n\n return self.db.insert_record(record=record)\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.get_app","title":"
get_app(app_id=None)","text":"
Look up a app from the database.
Source code in
trulens_eval/trulens_eval/tru.py def get_app(self, app_id: Optional[str] = None) -> JSON:\n\"\"\"\n Look up a app from the database.\n \"\"\"\n\n return self.db.get_app(app_id)\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.get_apps","title":"
get_apps()","text":"
Look up all apps from the database.
Source code in
trulens_eval/trulens_eval/tru.py def get_apps(self) -> Iterable[JSON]:\n\"\"\"\n Look up all apps from the database.\n \"\"\"\n\n return self.db.get_apps()\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.get_leaderboard","title":"
get_leaderboard(app_ids)","text":"
Get a leaderboard by app id from the database. Pass an empty list of app_ids to return all.
tru.get_leaderboard(app_ids=[])\n
Source code in
trulens_eval/trulens_eval/tru.py def get_leaderboard(self, app_ids: List[str]):\n\"\"\"\n Get a leaderboard by app id from the\n database. Pass an empty list of app_ids to return all.\n\n ```python\n tru.get_leaderboard(app_ids=[])\n ```\n \"\"\"\n df, feedback_cols = self.db.get_records_and_feedback(app_ids)\n\n col_agg_list = feedback_cols + ['latency', 'total_cost']\n\n leaderboard = df.groupby('app_id')[col_agg_list].mean().sort_values(\n by=feedback_cols, ascending=False\n )\n\n return leaderboard\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.get_records_and_feedback","title":"
get_records_and_feedback(app_ids)","text":"
Get records, their feeback results, and feedback names from the database. Pass an empty list of app_ids to return all.
tru.get_records_and_feedback(app_ids=[])\n
Source code in
trulens_eval/trulens_eval/tru.py def get_records_and_feedback(self, app_ids: List[str]):\n\"\"\"\n Get records, their feeback results, and feedback names from the\n database. Pass an empty list of app_ids to return all.\n\n ```python\n tru.get_records_and_feedback(app_ids=[])\n ```\n \"\"\"\n\n df, feedback_columns = self.db.get_records_and_feedback(app_ids)\n\n return df, feedback_columns\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.migrate_database","title":"
migrate_database()","text":"
Migrates the database. This should be run whenever there are breaking changes in a database created with an older version of trulens_eval.
Source code in
trulens_eval/trulens_eval/tru.py def migrate_database(self):\n\"\"\"\n Migrates the database. This should be run whenever there are breaking\n changes in a database created with an older version of trulens_eval.\n \"\"\"\n\n self.db.migrate_database()\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.reset_database","title":"
reset_database()","text":"
Reset the database. Clears all tables.
Source code in
trulens_eval/trulens_eval/tru.py def reset_database(self):\n\"\"\"\n Reset the database. Clears all tables.\n \"\"\"\n\n self.db.reset_database()\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.run_dashboard","title":"
run_dashboard(force=False, _dev=None)","text":"
Run a streamlit dashboard to view logged results and apps.
Parameters:
Name Type Description Default
- force bool: Stop existing dashboard(s) first.
required
- _dev Optional[Path]: If given, run dashboard with the given PYTHONPATH. This can be used to run the dashboard from outside of its pip package installation folder.
required
Raises:
Type Description
-ValueError Dashboard is already running.
Returns:
Type Description
Process - Process: Process containing streamlit dashboard.
Source code in
trulens_eval/trulens_eval/tru.py def run_dashboard(\n self, force: bool = False, _dev: Optional[Path] = None\n) -> Process:\n\"\"\"\n Run a streamlit dashboard to view logged results and apps.\n\n Args:\n\n - force: bool: Stop existing dashboard(s) first.\n\n - _dev: Optional[Path]: If given, run dashboard with the given\n PYTHONPATH. This can be used to run the dashboard from outside of\n its pip package installation folder.\n\n Raises:\n\n - ValueError: Dashboard is already running.\n\n Returns:\n\n - Process: Process containing streamlit dashboard.\n \"\"\"\n\n if force:\n self.stop_dashboard(force=force)\n\n print(\"Starting dashboard ...\")\n\n # Create .streamlit directory if it doesn't exist\n streamlit_dir = os.path.join(os.getcwd(), '.streamlit')\n os.makedirs(streamlit_dir, exist_ok=True)\n\n # Create config.toml file path\n config_path = os.path.join(streamlit_dir, 'config.toml')\n\n # Check if the file already exists\n if not os.path.exists(config_path):\n with open(config_path, 'w') as f:\n f.write('[theme]\\n')\n f.write('primaryColor=\"#0A2C37\"\\n')\n f.write('backgroundColor=\"#FFFFFF\"\\n')\n f.write('secondaryBackgroundColor=\"F5F5F5\"\\n')\n f.write('textColor=\"#0A2C37\"\\n')\n f.write('font=\"sans serif\"\\n')\n else:\n print(\"Config file already exists. Skipping writing process.\")\n\n # Create credentials.toml file path\n cred_path = os.path.join(streamlit_dir, 'credentials.toml')\n\n # Check if the file already exists\n if not os.path.exists(cred_path):\n with open(cred_path, 'w') as f:\n f.write('[general]\\n')\n f.write('email=\"\"\\n')\n else:\n print(\"Credentials file already exists. Skipping writing process.\")\n\n #run leaderboard with subprocess\n leaderboard_path = pkg_resources.resource_filename(\n 'trulens_eval', 'Leaderboard.py'\n )\n\n if Tru.dashboard_proc is not None:\n print(\"Dashboard already running at path:\", Tru.dashboard_urls)\n return Tru.dashboard_proc\n\n env_opts = {}\n if _dev is not None:\n env_opts['env'] = os.environ\n env_opts['env']['PYTHONPATH'] = str(_dev)\n\n proc = subprocess.Popen(\n [\n \"streamlit\", \"run\", \"--server.headless=True\", leaderboard_path,\n \"--\", \"--database-url\",\n self.db.engine.url.render_as_string(hide_password=False)\n ],\n stdout=subprocess.PIPE,\n stderr=subprocess.PIPE,\n text=True,\n **env_opts\n )\n\n started = threading.Event()\n tunnel_started = threading.Event()\n if is_notebook():\n out_stdout, out_stderr = setup_widget_stdout_stderr()\n else:\n out_stdout = None\n out_stderr = None\n\n IN_COLAB = 'google.colab' in sys.modules\n if IN_COLAB:\n tunnel_proc = subprocess.Popen(\n [\"npx\", \"localtunnel\", \"--port\", \"8501\"],\n stdout=subprocess.PIPE,\n stderr=subprocess.PIPE,\n text=True,\n **env_opts\n )\n\n def listen_to_tunnel(proc: subprocess.Popen, pipe, out, started):\n while proc.poll() is None:\n\n line = pipe.readline()\n if \"url\" in line:\n started.set()\n line = \"Go to this url and submit the ip given here. \" + line\n\n if out is not None:\n out.append_stdout(line)\n\n else:\n print(line)\n\n Tru.tunnel_listener_stdout = Thread(\n target=listen_to_tunnel,\n args=(\n tunnel_proc, tunnel_proc.stdout, out_stdout, tunnel_started\n )\n )\n Tru.tunnel_listener_stderr = Thread(\n target=listen_to_tunnel,\n args=(\n tunnel_proc, tunnel_proc.stderr, out_stderr, tunnel_started\n )\n )\n Tru.tunnel_listener_stdout.daemon = True\n Tru.tunnel_listener_stderr.daemon = True\n Tru.tunnel_listener_stdout.start()\n Tru.tunnel_listener_stderr.start()\n if not tunnel_started.wait(timeout=DASHBOARD_START_TIMEOUT\n ): # This might not work on windows.\n raise RuntimeError(\"Tunnel failed to start in time. \")\n\n def listen_to_dashboard(proc: subprocess.Popen, pipe, out, started):\n while proc.poll() is None:\n line = pipe.readline()\n if IN_COLAB:\n if \"External URL: \" in line:\n started.set()\n line = line.replace(\n \"External URL: http://\", \"Submit this IP Address: \"\n )\n line = line.replace(\":8501\", \"\")\n if out is not None:\n out.append_stdout(line)\n else:\n print(line)\n Tru.dashboard_urls = line # store the url when dashboard is started\n else:\n if \"Network URL: \" in line:\n url = line.split(\": \")[1]\n url = url.rstrip()\n print(f\"Dashboard started at {url} .\")\n started.set()\n Tru.dashboard_urls = line # store the url when dashboard is started\n if out is not None:\n out.append_stdout(line)\n else:\n print(line)\n if out is not None:\n out.append_stdout(\"Dashboard closed.\")\n else:\n print(\"Dashboard closed.\")\n\n Tru.dashboard_listener_stdout = Thread(\n target=listen_to_dashboard,\n args=(proc, proc.stdout, out_stdout, started)\n )\n Tru.dashboard_listener_stderr = Thread(\n target=listen_to_dashboard,\n args=(proc, proc.stderr, out_stderr, started)\n )\n\n # Purposely block main process from ending and wait for dashboard.\n Tru.dashboard_listener_stdout.daemon = False\n Tru.dashboard_listener_stderr.daemon = False\n\n Tru.dashboard_listener_stdout.start()\n Tru.dashboard_listener_stderr.start()\n\n Tru.dashboard_proc = proc\n\n wait_period = DASHBOARD_START_TIMEOUT\n if IN_COLAB:\n # Need more time to setup 2 processes tunnel and dashboard\n wait_period = wait_period * 3\n if not started.wait(timeout=wait_period\n ): # This might not work on windows.\n raise RuntimeError(\n \"Dashboard failed to start in time. \"\n \"Please inspect dashboard logs for additional information.\"\n )\n\n return proc\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.run_dashboard_in_jupyter","title":"
run_dashboard_in_jupyter()","text":"
Experimental approach to attempt to display the dashboard inside a jupyter notebook. Relies on the streamlit_jupyter package.
Source code in
trulens_eval/trulens_eval/tru.py def run_dashboard_in_jupyter(self):\n\"\"\"\n Experimental approach to attempt to display the dashboard inside a\n jupyter notebook. Relies on the `streamlit_jupyter` package.\n \"\"\"\n # EXPERIMENTAL\n # TODO: check for jupyter\n\n logger.warning(\n \"Running dashboard inside a notebook is an experimental feature and may not work well.\"\n )\n\n from streamlit_jupyter import StreamlitPatcher\n StreamlitPatcher().jupyter()\n from trulens_eval import Leaderboard\n\n Leaderboard.main()\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.run_feedback_functions","title":"
run_feedback_functions(record, feedback_functions, app=None)","text":"
Run a collection of feedback functions and report their result.
Parameters:
Name Type Description Default
record Record The record on which to evaluate the feedback
required
app App The app that produced the given record.
None feedback_functions Sequence[Feedback] A collection of feedback
required
Yields FeedbackResult, one for each element of feedback_functions potentially in random order.
Source code in
trulens_eval/trulens_eval/tru.py def run_feedback_functions(\n self,\n record: Record,\n feedback_functions: Sequence[Feedback],\n app: Optional[AppDefinition] = None,\n) -> Iterable[FeedbackResult]:\n\"\"\"\n Run a collection of feedback functions and report their result.\n\n Parameters:\n\n record (Record): The record on which to evaluate the feedback\n functions.\n\n app (App, optional): The app that produced the given record.\n If not provided, it is looked up from the given database `db`.\n\n feedback_functions (Sequence[Feedback]): A collection of feedback\n functions to evaluate.\n\n Yields `FeedbackResult`, one for each element of `feedback_functions`\n potentially in random order.\n \"\"\"\n\n for res in as_completed(self._submit_feedback_functions(\n record=record, feedback_functions=feedback_functions, app=app)):\n\n yield res.result()[1]\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.start_evaluator","title":"
start_evaluator(restart=False, fork=False)","text":"
Start a deferred feedback function evaluation thread.
Source code in
trulens_eval/trulens_eval/tru.py def start_evaluator(self,\n restart=False,\n fork=False) -> Union[Process, Thread]:\n\"\"\"\n Start a deferred feedback function evaluation thread.\n \"\"\"\n\n assert not fork, \"Fork mode not yet implemented.\"\n\n if self.evaluator_proc is not None:\n if restart:\n self.stop_evaluator()\n else:\n raise RuntimeError(\n \"Evaluator is already running in this process.\"\n )\n\n if not fork:\n self.evaluator_stop = threading.Event()\n\n def runloop():\n assert self.evaluator_stop is not None\n\n while fork or not self.evaluator_stop.is_set():\n futures = Feedback.evaluate_deferred(tru=self)\n\n if len(futures) > 0:\n print(\n f\"{UNICODE_YIELD}{UNICODE_YIELD}{UNICODE_YIELD} Started {len(futures)} deferred feedback functions.\"\n )\n wait(futures)\n print(\n f\"{UNICODE_CHECK}{UNICODE_CHECK}{UNICODE_CHECK} Finished evaluating deferred feedback functions.\"\n )\n\n if fork:\n sleep(10)\n else:\n self.evaluator_stop.wait(10)\n\n print(\"Evaluator stopped.\")\n\n if fork:\n proc = Process(target=runloop)\n else:\n proc = Thread(target=runloop)\n proc.daemon = True\n\n # Start a persistent thread or process that evaluates feedback functions.\n\n self.evaluator_proc = proc\n proc.start()\n\n return proc\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.stop_dashboard","title":"
stop_dashboard(force=False)","text":"
Stop existing dashboard(s) if running.
Parameters:
Name Type Description Default
- force bool: Also try to find any other dashboard processes not started in this notebook and shut them down too.
required
Raises:
Type Description
-ValueError Dashboard is not running.
Source code in
trulens_eval/trulens_eval/tru.py def stop_dashboard(self, force: bool = False) -> None:\n\"\"\"\n Stop existing dashboard(s) if running.\n\n Args:\n\n - force: bool: Also try to find any other dashboard processes not\n started in this notebook and shut them down too.\n\n Raises:\n\n - ValueError: Dashboard is not running.\n \"\"\"\n if Tru.dashboard_proc is None:\n if not force:\n raise ValueError(\n \"Dashboard not running in this workspace. \"\n \"You may be able to shut other instances by setting the `force` flag.\"\n )\n\n else:\n if sys.platform.startswith(\"win\"):\n raise RuntimeError(\n \"Force stop option is not supported on windows.\"\n )\n\n print(\"Force stopping dashboard ...\")\n import os\n import pwd # PROBLEM: does not exist on windows\n\n import psutil\n username = pwd.getpwuid(os.getuid())[0]\n for p in psutil.process_iter():\n try:\n cmd = \" \".join(p.cmdline())\n if \"streamlit\" in cmd and \"Leaderboard.py\" in cmd and p.username(\n ) == username:\n print(f\"killing {p}\")\n p.kill()\n except Exception as e:\n continue\n\n else:\n Tru.dashboard_proc.kill()\n Tru.dashboard_proc = None\n
"},{"location":"trulens_eval/api/tru/#trulens_eval.trulens_eval.tru.Tru.stop_evaluator","title":"
stop_evaluator()","text":"
Stop the deferred feedback evaluation thread.
Source code in
trulens_eval/trulens_eval/tru.py def stop_evaluator(self):\n\"\"\"\n Stop the deferred feedback evaluation thread.\n \"\"\"\n\n if self.evaluator_proc is None:\n raise RuntimeError(\"Evaluator not running this process.\")\n\n if isinstance(self.evaluator_proc, Process):\n self.evaluator_proc.terminate()\n\n elif isinstance(self.evaluator_proc, Thread):\n self.evaluator_stop.set()\n self.evaluator_proc.join()\n self.evaluator_stop = None\n\n self.evaluator_proc = None\n
"},{"location":"trulens_eval/api/trubasicapp/","title":"Tru Basic App","text":""},{"location":"trulens_eval/api/trubasicapp/#trulens_eval.trulens_eval.tru_basic_app--basic-input-output-instrumentation-and-monitoring","title":"Basic input output instrumentation and monitoring.","text":""},{"location":"trulens_eval/api/trubasicapp/#trulens_eval.trulens_eval.tru_basic_app.TruBasicApp","title":"
TruBasicApp","text":"
Bases: App
Instantiates a Basic app that makes little assumptions. Assumes input text and output text.
Usage:
def custom_application(prompt: str) -> str:\n return \"a response\"\n\nfrom trulens_eval import TruBasicApp\n# f_lang_match, f_qa_relevance, f_qs_relevance are feedback functions\ntru_recorder = TruBasicApp(custom_application, \n app_id=\"Custom Application v1\",\n feedbacks=[f_lang_match, f_qa_relevance, f_qs_relevance])\n\n# Basic app works by turning your callable into an app\n# This app is accessbile with the `app` attribute in the recorder\nwith tru_recorder as recording:\n tru_recorder.app(question)\n\ntru_record = recording.records[0]\n
See Feedback Functions for instantiating feedback functions.
Parameters:
Name Type Description Default
text_to_text Callable A text to text callable.
None Source code in
trulens_eval/trulens_eval/tru_basic_app.py class TruBasicApp(App):\n\"\"\"Instantiates a Basic app that makes little assumptions. Assumes input text and output text.\n\n **Usage:**\n\n ```\n def custom_application(prompt: str) -> str:\n return \"a response\"\n\n from trulens_eval import TruBasicApp\n # f_lang_match, f_qa_relevance, f_qs_relevance are feedback functions\n tru_recorder = TruBasicApp(custom_application, \n app_id=\"Custom Application v1\",\n feedbacks=[f_lang_match, f_qa_relevance, f_qs_relevance])\n\n # Basic app works by turning your callable into an app\n # This app is accessbile with the `app` attribute in the recorder\n with tru_recorder as recording:\n tru_recorder.app(question)\n\n tru_record = recording.records[0]\n\n ```\n See [Feedback Functions](https://www.trulens.org/trulens_eval/api/feedback/) for instantiating feedback functions.\n\n Args:\n text_to_text (Callable): A text to text callable.\n \"\"\"\n app: TruWrapperApp\n\n root_callable: ClassVar[FunctionOrMethod] = Field(\n default_factory=lambda: FunctionOrMethod.\n of_callable(TruWrapperApp._call),\n const=True\n )\n\n def __init__(\n self,\n text_to_text: Optional[Callable] = None,\n app: Optional[TruWrapperApp] = None,\n **kwargs\n ):\n\"\"\"\n Wrap a callable for monitoring.\n\n Arguments:\n - text_to_text: A function with signature string to string.\n - More args in App\n - More args in AppDefinition\n - More args in WithClassInfo\n \"\"\"\n\n super().update_forward_refs()\n if text_to_text is not None:\n app = TruWrapperApp(text_to_text)\n else:\n assert app is not None, \"Need to provide either `app: TruWrapperApp` or a `text_to_text: Callable`.\"\n\n kwargs['app'] = app\n kwargs['root_class'] = Class.of_object(app)\n kwargs['instrument'] = TruBasicCallableInstrument(app=self)\n\n super().__init__(**kwargs)\n\n # Setup the DB-related things:\n self.post_init()\n\n def main_call(self, human: str) -> str:\n # If available, a single text to a single text invocation of this app.\n\n return self.app._call(human)\n\n async def main_acall(self, human: str) -> str:\n # If available, a single text to a single text invocation of this app.\n raise NotImplementedError()\n\n def main_input(\n self, func: Callable, sig: Signature, bindings: BoundArguments\n ) -> str:\n\n if func == getattr(TruWrapperApp._call, Instrument.INSTRUMENT):\n # If func is the wrapper app _call, replace the signature and\n # bindings based on the actual containing callable instead of\n # self.app._call . This needs to be done since the a TruWrapperApp\n # may be wrapping apps with different signatures on their callables\n # so TruWrapperApp._call cannot have a consistent signature\n # statically. Note also we are looking up the Instrument.INSTRUMENT\n # attribute here since the method is instrumented and overridden by\n # another wrapper in the process with the original accessible at\n # this attribute.\n\n sig = signature(self.app._call_fn)\n # Skipping self as TruWrapperApp._call takes in self, but\n # self.app._call_fn does not.\n bindings = sig.bind(*bindings.args[1:], **bindings.kwargs)\n\n return super().main_input(func, sig, bindings)\n\n def call_with_record(self, *args, **kwargs):\n\"\"\"\n Run the callable with the given arguments. Note that the wrapped\n callable is expected to take in a single string.\n\n Returns:\n dict: record metadata\n \"\"\"\n # NOTE: Actually text_to_text can take in more args.\n\n self._with_dep_message(method=\"call\", is_async=False, with_record=True)\n\n return self.with_record(self.app._call, *args, **kwargs)\n
"},{"location":"trulens_eval/api/trubasicapp/#trulens_eval.trulens_eval.tru_basic_app.TruBasicApp.__init__","title":"
__init__(text_to_text=None, app=None, **kwargs)","text":"
Wrap a callable for monitoring.
- text_to_text: A function with signature string to string.
- More args in App
- More args in AppDefinition
- More args in WithClassInfo
Source code in
trulens_eval/trulens_eval/tru_basic_app.py def __init__(\n self,\n text_to_text: Optional[Callable] = None,\n app: Optional[TruWrapperApp] = None,\n **kwargs\n):\n\"\"\"\n Wrap a callable for monitoring.\n\n Arguments:\n - text_to_text: A function with signature string to string.\n - More args in App\n - More args in AppDefinition\n - More args in WithClassInfo\n \"\"\"\n\n super().update_forward_refs()\n if text_to_text is not None:\n app = TruWrapperApp(text_to_text)\n else:\n assert app is not None, \"Need to provide either `app: TruWrapperApp` or a `text_to_text: Callable`.\"\n\n kwargs['app'] = app\n kwargs['root_class'] = Class.of_object(app)\n kwargs['instrument'] = TruBasicCallableInstrument(app=self)\n\n super().__init__(**kwargs)\n\n # Setup the DB-related things:\n self.post_init()\n
"},{"location":"trulens_eval/api/trubasicapp/#trulens_eval.trulens_eval.tru_basic_app.TruBasicApp.call_with_record","title":"
call_with_record(*args, **kwargs)","text":"
Run the callable with the given arguments. Note that the wrapped callable is expected to take in a single string.
Returns:
Name Type Description
dict record metadata
Source code in
trulens_eval/trulens_eval/tru_basic_app.py def call_with_record(self, *args, **kwargs):\n\"\"\"\n Run the callable with the given arguments. Note that the wrapped\n callable is expected to take in a single string.\n\n Returns:\n dict: record metadata\n \"\"\"\n # NOTE: Actually text_to_text can take in more args.\n\n self._with_dep_message(method=\"call\", is_async=False, with_record=True)\n\n return self.with_record(self.app._call, *args, **kwargs)\n
"},{"location":"trulens_eval/api/truchain/","title":"Tru Chain","text":""},{"location":"trulens_eval/api/truchain/#trulens_eval.trulens_eval.tru_chain--langchain-instrumentation-and-monitoring","title":"Langchain instrumentation and monitoring.","text":""},{"location":"trulens_eval/api/truchain/#trulens_eval.trulens_eval.tru_chain.TruChain","title":"
TruChain","text":"
Bases: App
Instantiates the Langchain Wrapper.
Usage:
Langchain Code: Langchain Quickstart
# Code snippet taken from langchain 0.0.281 (API subject to change with new versions)\nfrom langchain.chains import LLMChain\nfrom langchain.llms import OpenAI\nfrom langchain.prompts.chat import ChatPromptTemplate\nfrom langchain.prompts.chat import HumanMessagePromptTemplate\nfrom langchain.prompts.chat import PromptTemplate\n\nfull_prompt = HumanMessagePromptTemplate(\n prompt=PromptTemplate(\n template=\n \"Provide a helpful response with relevant background information for the following: {prompt}\",\n input_variables=[\"prompt\"],\n )\n)\n\nchat_prompt_template = ChatPromptTemplate.from_messages([full_prompt])\n\nllm = OpenAI(temperature=0.9, max_tokens=128)\n\nchain = LLMChain(llm=llm, prompt=chat_prompt_template, verbose=True)\n
Trulens Eval Code:
from trulens_eval import TruChain\n# f_lang_match, f_qa_relevance, f_qs_relevance are feedback functions\ntru_recorder = TruChain(\n chain,\n app_id='Chain1_ChatApplication',\n feedbacks=[f_lang_match, f_qa_relevance, f_qs_relevance])\n)\nwith tru_recorder as recording:\n chain(\"\"What is langchain?\")\n\ntru_record = recording.records[0]\n\n# To add record metadata \nwith tru_recorder as recording:\n recording.record_metadata=\"this is metadata for all records in this context that follow this line\"\n chain(\"What is langchain?\")\n recording.record_metadata=\"this is different metadata for all records in this context that follow this line\"\n chain(\"Where do I download langchain?\")\n
See Feedback Functions for instantiating feedback functions.
Parameters:
Name Type Description Default
app Chain A langchain application.
required Source code in
trulens_eval/trulens_eval/tru_chain.py class TruChain(App):\n\"\"\"Instantiates the Langchain Wrapper.\n\n **Usage:**\n\n Langchain Code: [Langchain Quickstart](https://python.langchain.com/docs/get_started/quickstart)\n ```\n # Code snippet taken from langchain 0.0.281 (API subject to change with new versions)\n from langchain.chains import LLMChain\n from langchain.llms import OpenAI\n from langchain.prompts.chat import ChatPromptTemplate\n from langchain.prompts.chat import HumanMessagePromptTemplate\n from langchain.prompts.chat import PromptTemplate\n\n full_prompt = HumanMessagePromptTemplate(\n prompt=PromptTemplate(\n template=\n \"Provide a helpful response with relevant background information for the following: {prompt}\",\n input_variables=[\"prompt\"],\n )\n )\n\n chat_prompt_template = ChatPromptTemplate.from_messages([full_prompt])\n\n llm = OpenAI(temperature=0.9, max_tokens=128)\n\n chain = LLMChain(llm=llm, prompt=chat_prompt_template, verbose=True)\n\n ```\n\n Trulens Eval Code:\n ```\n\n from trulens_eval import TruChain\n # f_lang_match, f_qa_relevance, f_qs_relevance are feedback functions\n tru_recorder = TruChain(\n chain,\n app_id='Chain1_ChatApplication',\n feedbacks=[f_lang_match, f_qa_relevance, f_qs_relevance])\n )\n with tru_recorder as recording:\n chain(\"\"What is langchain?\")\n\n tru_record = recording.records[0]\n\n # To add record metadata \n with tru_recorder as recording:\n recording.record_metadata=\"this is metadata for all records in this context that follow this line\"\n chain(\"What is langchain?\")\n recording.record_metadata=\"this is different metadata for all records in this context that follow this line\"\n chain(\"Where do I download langchain?\")\n ```\n See [Feedback Functions](https://www.trulens.org/trulens_eval/api/feedback/) for instantiating feedback functions.\n\n Args:\n app (Chain): A langchain application.\n \"\"\"\n\n app: Chain\n\n # TODO: what if _acall is being used instead?\n root_callable: ClassVar[FunctionOrMethod] = Field(\n default_factory=lambda: FunctionOrMethod.of_callable(TruChain._call),\n const=True\n )\n\n # Normally pydantic does not like positional args but chain here is\n # important enough to make an exception.\n def __init__(self, app: Chain, **kwargs):\n\"\"\"\n Wrap a langchain chain for monitoring.\n\n Arguments:\n - app: Chain -- the chain to wrap.\n - More args in App\n - More args in AppDefinition\n - More args in WithClassInfo\n \"\"\"\n\n super().update_forward_refs()\n\n # TruChain specific:\n kwargs['app'] = app\n kwargs['root_class'] = Class.of_object(app)\n kwargs['instrument'] = LangChainInstrument(app=self)\n\n super().__init__(**kwargs)\n\n self.post_init()\n\n # TODEP\n # Chain requirement\n @property\n def _chain_type(self):\n return \"TruChain\"\n\n # TODEP\n # Chain requirement\n @property\n def input_keys(self) -> List[str]:\n return self.app.input_keys\n\n # TODEP\n # Chain requirement\n @property\n def output_keys(self) -> List[str]:\n return self.app.output_keys\n\n def main_input(\n self, func: Callable, sig: Signature, bindings: BoundArguments\n ) -> str:\n\"\"\"\n Determine the main input string for the given function `func` with\n signature `sig` if it is to be called with the given bindings\n `bindings`.\n \"\"\"\n\n if 'inputs' in bindings.arguments:\n # langchain specific:\n ins = self.app.prep_inputs(bindings.arguments['inputs'])\n\n if len(self.app.input_keys) == 0:\n logger.warning(\n \"langchain app has no inputs. `main_input` will be `None`.\"\n )\n return None\n\n return ins[self.app.input_keys[0]]\n\n return App.main_input(self, func, sig, bindings)\n\n def main_output(\n self, func: Callable, sig: Signature, bindings: BoundArguments, ret: Any\n ) -> str:\n\"\"\"\n Determine the main out string for the given function `func` with\n signature `sig` after it is called with the given `bindings` and has\n returned `ret`.\n \"\"\"\n\n if isinstance(ret, Dict):\n # langchain specific:\n if self.app.output_keys[0] in ret:\n return ret[self.app.output_keys[0]]\n\n return App.main_output(self, func, sig, bindings, ret)\n\n def main_call(self, human: str):\n # If available, a single text to a single text invocation of this app.\n\n out_key = self.app.output_keys[0]\n\n return self.app(human)[out_key]\n\n async def main_acall(self, human: str):\n # If available, a single text to a single text invocation of this app.\n\n out_key = self.app.output_keys[0]\n\n return await self._acall(human)[out_key]\n\n def __getattr__(self, __name: str) -> Any:\n # A message for cases where a user calls something that the wrapped\n # chain has but we do not wrap yet.\n\n if safe_hasattr(self.app, __name):\n return RuntimeError(\n f\"TruChain has no attribute {__name} but the wrapped app ({type(self.app)}) does. \",\n f\"If you are calling a {type(self.app)} method, retrieve it from that app instead of from `TruChain`. \"\n f\"TruChain presently only wraps Chain.__call__, Chain._call, and Chain._acall .\"\n )\n else:\n raise RuntimeError(f\"TruChain has no attribute named {__name}.\")\n\n # NOTE: Input signature compatible with langchain.chains.base.Chain.acall\n # TODEP\n async def acall_with_record(self, *args, **kwargs) -> Tuple[Any, Record]:\n\"\"\"\n Run the chain acall method and also return a record metadata object.\n \"\"\"\n\n self._with_dep_message(method=\"acall\", is_async=True, with_record=True)\n\n return await self.awith_record(self.app.acall, *args, **kwargs)\n\n # NOTE: Input signature compatible with langchain.chains.base.Chain.__call__\n # TODEP\n def call_with_record(self, *args, **kwargs) -> Tuple[Any, Record]:\n\"\"\"\n Run the chain call method and also return a record metadata object.\n \"\"\"\n\n self._with_dep_message(\n method=\"__call__\", is_async=False, with_record=True\n )\n\n return self.with_record(self.app.__call__, *args, **kwargs)\n\n # TODEP\n # Mimics Chain\n def __call__(self, *args, **kwargs) -> Dict[str, Any]:\n\"\"\"\n Wrapped call to self.app._call with instrumentation. If you need to\n get the record, use `call_with_record` instead. \n \"\"\"\n\n self._with_dep_message(\n method=\"__call__\", is_async=False, with_record=False\n )\n\n return self.with_(self.app, *args, **kwargs)\n\n # TODEP\n # Chain requirement\n def _call(self, *args, **kwargs) -> Any:\n\n self._with_dep_message(\n method=\"_call\", is_async=False, with_record=False\n )\n\n ret, _ = self.with_(self.app._call, *args, **kwargs)\n\n return ret\n\n # TODEP\n # Optional Chain requirement\n async def _acall(self, *args, **kwargs) -> Any:\n\n self._with_dep_message(\n method=\"_acall\", is_async=True, with_record=False\n )\n\n ret, _ = await self.awith_(self.app.acall, *args, **kwargs)\n\n return ret\n
"},{"location":"trulens_eval/api/truchain/#trulens_eval.trulens_eval.tru_chain.TruChain.__call__","title":"
__call__(*args, **kwargs)","text":"
Wrapped call to self.app._call with instrumentation. If you need to get the record, use call_with_record instead.
Source code in
trulens_eval/trulens_eval/tru_chain.py def __call__(self, *args, **kwargs) -> Dict[str, Any]:\n\"\"\"\n Wrapped call to self.app._call with instrumentation. If you need to\n get the record, use `call_with_record` instead. \n \"\"\"\n\n self._with_dep_message(\n method=\"__call__\", is_async=False, with_record=False\n )\n\n return self.with_(self.app, *args, **kwargs)\n
"},{"location":"trulens_eval/api/truchain/#trulens_eval.trulens_eval.tru_chain.TruChain.__init__","title":"
__init__(app, **kwargs)","text":"
Wrap a langchain chain for monitoring.
- app: Chain -- the chain to wrap.
- More args in App
- More args in AppDefinition
- More args in WithClassInfo
Source code in
trulens_eval/trulens_eval/tru_chain.py def __init__(self, app: Chain, **kwargs):\n\"\"\"\n Wrap a langchain chain for monitoring.\n\n Arguments:\n - app: Chain -- the chain to wrap.\n - More args in App\n - More args in AppDefinition\n - More args in WithClassInfo\n \"\"\"\n\n super().update_forward_refs()\n\n # TruChain specific:\n kwargs['app'] = app\n kwargs['root_class'] = Class.of_object(app)\n kwargs['instrument'] = LangChainInstrument(app=self)\n\n super().__init__(**kwargs)\n\n self.post_init()\n
"},{"location":"trulens_eval/api/truchain/#trulens_eval.trulens_eval.tru_chain.TruChain.acall_with_record","title":"
acall_with_record(*args, **kwargs) async","text":"
Run the chain acall method and also return a record metadata object.
Source code in
trulens_eval/trulens_eval/tru_chain.py async def acall_with_record(self, *args, **kwargs) -> Tuple[Any, Record]:\n\"\"\"\n Run the chain acall method and also return a record metadata object.\n \"\"\"\n\n self._with_dep_message(method=\"acall\", is_async=True, with_record=True)\n\n return await self.awith_record(self.app.acall, *args, **kwargs)\n
"},{"location":"trulens_eval/api/truchain/#trulens_eval.trulens_eval.tru_chain.TruChain.call_with_record","title":"
call_with_record(*args, **kwargs)","text":"
Run the chain call method and also return a record metadata object.
Source code in
trulens_eval/trulens_eval/tru_chain.py def call_with_record(self, *args, **kwargs) -> Tuple[Any, Record]:\n\"\"\"\n Run the chain call method and also return a record metadata object.\n \"\"\"\n\n self._with_dep_message(\n method=\"__call__\", is_async=False, with_record=True\n )\n\n return self.with_record(self.app.__call__, *args, **kwargs)\n
"},{"location":"trulens_eval/api/truchain/#trulens_eval.trulens_eval.tru_chain.TruChain.main_input","title":"
main_input(func, sig, bindings)","text":"
Determine the main input string for the given function func with signature sig if it is to be called with the given bindings bindings.
Source code in
trulens_eval/trulens_eval/tru_chain.py def main_input(\n self, func: Callable, sig: Signature, bindings: BoundArguments\n) -> str:\n\"\"\"\n Determine the main input string for the given function `func` with\n signature `sig` if it is to be called with the given bindings\n `bindings`.\n \"\"\"\n\n if 'inputs' in bindings.arguments:\n # langchain specific:\n ins = self.app.prep_inputs(bindings.arguments['inputs'])\n\n if len(self.app.input_keys) == 0:\n logger.warning(\n \"langchain app has no inputs. `main_input` will be `None`.\"\n )\n return None\n\n return ins[self.app.input_keys[0]]\n\n return App.main_input(self, func, sig, bindings)\n
"},{"location":"trulens_eval/api/truchain/#trulens_eval.trulens_eval.tru_chain.TruChain.main_output","title":"
main_output(func, sig, bindings, ret)","text":"
Determine the main out string for the given function func with signature sig after it is called with the given bindings and has returned ret.
Source code in
trulens_eval/trulens_eval/tru_chain.py def main_output(\n self, func: Callable, sig: Signature, bindings: BoundArguments, ret: Any\n) -> str:\n\"\"\"\n Determine the main out string for the given function `func` with\n signature `sig` after it is called with the given `bindings` and has\n returned `ret`.\n \"\"\"\n\n if isinstance(ret, Dict):\n # langchain specific:\n if self.app.output_keys[0] in ret:\n return ret[self.app.output_keys[0]]\n\n return App.main_output(self, func, sig, bindings, ret)\n
"},{"location":"trulens_eval/api/trucustom/","title":"Tru Custom App","text":""},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app--custom-class-apps","title":"Custom class Apps","text":"
This wrapper covers apps that are not based on one of the high-level frameworks such as langchain or llama-index. We instead assume that some python class or classes implements an app which has similar functionality to LLM apps coded in the high-level frameworks in that it generally processes text queries to produce text outputs while making intermediate queries to things like LLMs, vector DBs, and similar.
"},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app--example-usage","title":"Example Usage","text":"
Consider a mock question-answering app with a context retriever component coded up as two classes in two python, CustomApp and CustomRetriever:
"},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app--custom_apppy","title":"
custom_app.py","text":"
from trulens_eval.tru_custom_app import instrument\nfrom custom_retriever import CustomRetriever \n\n\nclass CustomApp:\n # NOTE: No restriction on this class.\n\n def __init__(self):\n self.retriever = CustomRetriever()\n\n @instrument\n def retrieve_chunks(self, data):\n return self.retriever.retrieve_chunks(data)\n\n @instrument\n def respond_to_query(self, input):\n chunks = self.retrieve_chunks(input) output = f\"The answer to {input} is\n probably {chunks[0]} or something ...\" return output\n
"},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app--custom_retrieverpy","title":"
custom_retriever.py","text":"
from trulens_eval.tru_custom_app import instrument\n\nclass CustomRetriever:\n # NOTE: No restriction on this class either.\n\n @instrument\n def retrieve_chunks(self, data):\n return [\n f\"Relevant chunk: {data.upper()}\", f\"Relevant chunk: {data[::-1]}\"\n ]\n
The core tool for instrumenting these classes is the instrument method (actually class, but details are not important here). trulens needs to be aware of two high-level concepts to usefully monitor the app: components and methods used by components. The instrument must decorate each method that the user wishes to watch (for it to show up on the dashboard). In the example, all of the functionalities are decorated. Additionally, the owner classes of any decorated method is viewed as an app component. In this case CustomApp and CustomRetriever are components.
Following the instrumentation, the app can be used with or without tracking:
"},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app--examplepy","title":"
example.py","text":"
from custom_app import CustomApp from trulens_eval.tru_custom_app\nimport TruCustomApp\n\nca = CustomApp()\n\n# Normal app Usage:\nresponse = ca.respond_to_query(\"What is the capital of Indonesia?\")\n\n# Wrapping app with `TruCustomApp`: \nta = TruCustomApp(ca)\n\n# Wrapped Usage: must use the general `with_record` (or `awith_record`) method:\nresponse, record = ta.with_record(\n ca.respond_to_query, input=\"What is the capital of Indonesia?\"\n)\n
The with_record use above returns both the response of the app normally produces as well as the record of the app as is the case with the higher-level wrappers. TruCustomApp constructor arguments are like in those higher-level apps as well including the feedback functions, metadata, etc.
"},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app--instrumenting-3rd-party-classes","title":"Instrumenting 3rd party classes","text":"
In cases you do not have access to a class to make the necessary decorations for tracking, you can instead use one of the static methods of instrument, for example, the alterative for making sure the custom retriever gets instrumented is via:
# custom_app.py`:\n\nfrom trulens_eval.tru_custom_app import instrument\nfrom somepackage.from custom_retriever import CustomRetriever\n\ninstrument.method(CustomRetriever, \"retrieve_chunks\")\n\n# ... rest of the custom class follows ...\n
"},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app--api-usage-tracking","title":"API Usage Tracking","text":"
Uses of python libraries for common LLMs like OpenAI are tracked in custom class apps.
"},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app--covered-llm-libraries","title":"Covered LLM Libraries","text":"
- Official OpenAI python package (https://github.com/openai/openai-python).
"},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app--huggingface","title":"Huggingface","text":"
Uses of huggingface inference APIs are tracked as long as requests are made through the requests class's post method to the URL https://api-inference.huggingface.co .
"},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app--limitations","title":"Limitations","text":"
-
Tracked (instrumented) components must be accessible through other tracked components. Specifically, an app cannot have a custom class that is not instrumented but that contains an instrumented class. The inner instrumented class will not be found by trulens.
-
All tracked components are categorized as \"Custom\" (as opposed to Template, LLM, etc.). That is, there is no categorization available for custom components. They will all show up as \"uncategorized\" in the dashboard.
-
Non json-like contents of components (that themselves are not components) are not recorded or available in dashboard. This can be alleviated to some extent with the app_extra_json argument to TruCustomClass as it allows one to specify in the form of json additional information to store alongside the component hierarchy. Json-like (json bases like string, int, and containers like sequences and dicts are included).
"},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app--what-can-go-wrong","title":"What can go wrong","text":"
- If a
with_record or awith_record call does not encounter any instrumented method, it will raise an error. You can check which methods are instrumented using App.print_instrumented. You may have forgotten to decorate relevant methods with @instrument.
app.print_instrumented()\n\n### output example:\nComponents:\n TruCustomApp (Other) at 0x171bd3380 with path *.__app__\n CustomApp (Custom) at 0x12114b820 with path *.__app__.app\n CustomLLM (Custom) at 0x12114be50 with path *.__app__.app.llm\n CustomMemory (Custom) at 0x12114bf40 with path *.__app__.app.memory\n CustomRetriever (Custom) at 0x12114bd60 with path *.__app__.app.retriever\n CustomTemplate (Custom) at 0x12114bf10 with path *.__app__.app.template\n\nMethods:\nObject at 0x12114b820:\n <function CustomApp.retrieve_chunks at 0x299132ca0> with path *.__app__.app\n <function CustomApp.respond_to_query at 0x299132d30> with path *.__app__.app\n <function CustomApp.arespond_to_query at 0x299132dc0> with path *.__app__.app\nObject at 0x12114be50:\n <function CustomLLM.generate at 0x299106b80> with path *.__app__.app.llm\nObject at 0x12114bf40:\n <function CustomMemory.remember at 0x299132670> with path *.__app__.app.memory\nObject at 0x12114bd60:\n <function CustomRetriever.retrieve_chunks at 0x299132790> with path *.__app__.app.retriever\nObject at 0x12114bf10:\n <function CustomTemplate.fill at 0x299132a60> with path *.__app__.app.template\n
- If an instrumented / decorated method's owner object cannot be found when traversing your custom class, you will get a warning. This may be ok in the end but may be indicative of a problem. Specifically, note the \"Tracked\" limitation above. You can also use the
app_extra_json argument to App / TruCustomApp to provide a structure to stand in place for (or augment) the data produced by walking over instrumented components to make sure this hierarchy contains the owner of each instrumented method.
The owner-not-found error looks like this:
Function <function CustomRetriever.retrieve_chunks at 0x177935d30> was not found during instrumentation walk. Make sure it is accessible by traversing app <custom_app.CustomApp object at 0x112a005b0> or provide a bound method for it as TruCustomApp constructor argument `methods_to_instrument`.\nFunction <function CustomTemplate.fill at 0x1779474c0> was not found during instrumentation walk. Make sure it is accessible by traversing app <custom_app.CustomApp object at 0x112a005b0> or provide a bound method for it as TruCustomApp constructor argument `methods_to_instrument`.\nFunction <function CustomLLM.generate at 0x1779471f0> was not found during instrumentation walk. Make sure it is accessible by traversing app <custom_app.CustomApp object at 0x112a005b0> or provide a bound method for it as TruCustomApp constructor argument `methods_to_instrument`.\n
Subsequent attempts at with_record/awith_record may result in the \"Empty record\" exception.
- Usage tracking not tracking. We presently have limited coverage over which APIs we track and make some assumptions with regards to accessible APIs through lower-level interfaces. Specifically, we only instrument the
requests module's post method for the lower level tracking. Please file an issue on github with your use cases so we can work out a more complete solution as needed.
"},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app.TruCustomApp","title":"
TruCustomApp","text":"
Bases: App
Instantiates a Custom App that can be tracked as long as methods are decorated with @instrument.
Usage:
from trulens_eval import instrument\n\nclass CustomApp:\n\n def __init__(self):\n self.retriever = CustomRetriever()\n self.llm = CustomLLM()\n self.template = CustomTemplate(\n \"The answer to {question} is probably {answer} or something ...\"\n )\n\n @instrument\n def retrieve_chunks(self, data):\n return self.retriever.retrieve_chunks(data)\n\n @instrument\n def respond_to_query(self, input):\n chunks = self.retrieve_chunks(input)\n answer = self.llm.generate(\",\".join(chunks))\n output = self.template.fill(question=input, answer=answer)\n\n return output\n\nca = CustomApp()\nfrom trulens_eval import TruCustomApp\n# f_lang_match, f_qa_relevance, f_qs_relevance are feedback functions\ntru_recorder = TruCustomApp(ca, \n app_id=\"Custom Application v1\",\n feedbacks=[f_lang_match, f_qa_relevance, f_qs_relevance])\n\nquestion = \"What is the capital of Indonesia?\"\n\n# Normal Usage:\nresponse_normal = ca.respond_to_query(question)\n\n# Instrumented Usage:\nwith tru_recorder as recording:\n ca.respond_to_query(question)\n\ntru_record = recording.records[0]\n\n# To add record metadata \nwith tru_recorder as recording:\n recording.record_metadata=\"this is metadata for all records in this context that follow this line\"\n ca.respond_to_query(\"What is llama 2?\")\n recording.record_metadata=\"this is different metadata for all records in this context that follow this line\"\n ca.respond_to_query(\"Where do I download llama 2?\")\n
See Feedback Functions for instantiating feedback functions.
Parameters:
Name Type Description Default
app Any Any class
required Source code in
trulens_eval/trulens_eval/tru_custom_app.py class TruCustomApp(App):\n\"\"\"Instantiates a Custom App that can be tracked as long as methods are decorated with @instrument.\n\n **Usage:**\n\n ```\n from trulens_eval import instrument\n\n class CustomApp:\n\n def __init__(self):\n self.retriever = CustomRetriever()\n self.llm = CustomLLM()\n self.template = CustomTemplate(\n \"The answer to {question} is probably {answer} or something ...\"\n )\n\n @instrument\n def retrieve_chunks(self, data):\n return self.retriever.retrieve_chunks(data)\n\n @instrument\n def respond_to_query(self, input):\n chunks = self.retrieve_chunks(input)\n answer = self.llm.generate(\",\".join(chunks))\n output = self.template.fill(question=input, answer=answer)\n\n return output\n\n ca = CustomApp()\n from trulens_eval import TruCustomApp\n # f_lang_match, f_qa_relevance, f_qs_relevance are feedback functions\n tru_recorder = TruCustomApp(ca, \n app_id=\"Custom Application v1\",\n feedbacks=[f_lang_match, f_qa_relevance, f_qs_relevance])\n\n question = \"What is the capital of Indonesia?\"\n\n # Normal Usage:\n response_normal = ca.respond_to_query(question)\n\n # Instrumented Usage:\n with tru_recorder as recording:\n ca.respond_to_query(question)\n\n tru_record = recording.records[0]\n\n # To add record metadata \n with tru_recorder as recording:\n recording.record_metadata=\"this is metadata for all records in this context that follow this line\"\n ca.respond_to_query(\"What is llama 2?\")\n recording.record_metadata=\"this is different metadata for all records in this context that follow this line\"\n ca.respond_to_query(\"Where do I download llama 2?\")\n\n ```\n See [Feedback Functions](https://www.trulens.org/trulens_eval/api/feedback/) for instantiating feedback functions.\n\n Args:\n app (Any): Any class\n \"\"\"\n app: Any\n\n root_callable: ClassVar[FunctionOrMethod] = Field(None)\n\n # Methods marked as needing instrumentation. These are checked to make sure\n # the object walk finds them. If not, a message is shown to let user know\n # how to let the TruCustomApp constructor know where these methods are.\n functions_to_instrument: ClassVar[Set[Callable]] = set([])\n\n main_method: Optional[Function] = None # serialized version of the below\n main_method_loaded: Optional[Callable] = Field(exclude=True)\n\n # main_async_method: Optional[Union[Callable, Method]] = None # = Field(exclude=True)\n\n def __init__(self, app: Any, methods_to_instrument=None, **kwargs):\n\"\"\"\n Wrap a custom class for recording.\n\n Arguments:\n - app: Any -- the custom app object being wrapped.\n - More args in App\n - More args in AppDefinition\n - More args in WithClassInfo\n \"\"\"\n\n kwargs['app'] = app\n kwargs['root_class'] = Class.of_object(app)\n\n instrument = Instrument(\n app=self # App mixes in WithInstrumentCallbacks\n )\n kwargs['instrument'] = instrument\n\n if 'main_method' in kwargs:\n main_method = kwargs['main_method']\n\n # TODO: ARGPARSE\n if isinstance(main_method, dict):\n main_method = Function(**main_method)\n\n if isinstance(main_method, Function):\n main_method_loaded = main_method.load()\n main_name = main_method.name\n\n cls = main_method.cls.load()\n mod = main_method.module.load().__name__\n\n else:\n main_name = main_method.__name__\n main_method_loaded = main_method\n\n if not safe_hasattr(main_method_loaded, \"__self__\"):\n raise ValueError(\n \"Please specify `main_method` as a bound method (like `someapp.somemethod` instead of `Someclass.somemethod`).\"\n )\n\n app_self = main_method_loaded.__self__\n\n assert app_self == app, \"`main_method`'s bound self must be the same as `app`.\"\n\n cls = app_self.__class__\n mod = cls.__module__\n\n instrument.include_modules.add(mod)\n instrument.include_classes.add(cls)\n instrument.include_methods[main_name] = lambda o: isinstance(o, cls)\n\n # This does instrumentation:\n super().__init__(**kwargs)\n\n # Needed to split this part to after the instrumentation so that the\n # getattr below gets the instrumented version of main method.\n if 'main_method' in kwargs:\n # Set main_method to the unbound version. Will be passing in app for\n # \"self\" manually when needed.\n main_method_loaded = getattr(cls, main_name)\n\n # This will be serialized as part of this TruCustomApp. Importatly, it is unbound.\n main_method = Function.of_function(main_method_loaded, cls=cls)\n\n self.main_method = main_method\n self.main_method_loaded = main_method_loaded\n\n methods_to_instrument = methods_to_instrument or dict()\n\n # The rest of this code instruments methods explicitly passed to\n # constructor as needing instrumentation and checks that methods\n # decorated with @instrument or passed explicitly belong to some\n # component as per serialized version of this app. If they are not,\n # placeholders are made in `app_extra_json` so that subsequent\n # serialization looks like the components exist.\n json = self.dict()\n\n for m, path in methods_to_instrument.items():\n method_name = m.__name__\n\n full_path = JSONPath().app + path\n\n self.instrument.instrument_method(\n method_name=method_name, obj=m.__self__, query=full_path\n )\n\n # TODO: DEDUP with next condition\n\n # Check whether the path/location of the method is in json serialization and\n # if not, add a placeholder to app_extra_json.\n try:\n next(full_path(json))\n\n print(\n f\"{UNICODE_CHECK} Added method {m.__name__} under component at path {full_path}\"\n )\n\n except Exception:\n logger.warning(\n f\"App has no component at path {full_path} . \"\n f\"Specify the component with the `app_extra_json` argument to TruCustomApp constructor. \"\n f\"Creating a placeholder there for now.\"\n )\n\n path.set(\n self.app_extra_json, {\n PLACEHOLDER:\n \"I was automatically added to `app_extra_json` because there was nothing here to refer to an instrumented method owner.\",\n m.__name__:\n f\"Placeholder for method {m.__name__}.\"\n }\n )\n\n # Check that any functions marked with `TruCustomApp.instrument` has been\n # instrumented as a method under some object.\n for f in TruCustomApp.functions_to_instrument:\n obj_ids_methods_and_full_paths = list(self._get_methods_for_func(f))\n\n if len(obj_ids_methods_and_full_paths) == 0:\n logger.warning(\n f\"Function {f} was not found during instrumentation walk. \"\n f\"Make sure it is accessible by traversing app {app} \"\n f\"or provide a bound method for it as TruCustomApp constructor argument `methods_to_instrument`.\"\n )\n\n else:\n for obj_id, m, full_path in obj_ids_methods_and_full_paths:\n try:\n next(full_path.get(json))\n\n except Exception as e:\n logger.warning(\n f\"App has no component owner of instrumented method {m} at path {full_path}. \"\n f\"Specify the component with the `app_extra_json` argument to TruCustomApp constructor. \"\n f\"Creating a placeholder there for now.\"\n )\n\n path.set(\n self.app_extra_json, {\n PLACEHOLDER:\n \"I was automatically added to `app_extra_json` because there was nothing here to refer to an instrumented method owner.\",\n m.__name__:\n f\"Placeholder for method {m.__name__}.\"\n }\n )\n\n # DB stuff and checks:\n self.post_init()\n\n def __getattr__(self, __name: str) -> Any:\n # A message for cases where a user calls something that the wrapped\n # app has but we do not wrap yet.\n\n print(__name)\n\n if safe_hasattr(self.app, __name):\n return RuntimeError(\n f\"TruCustomApp has no attribute {__name} but the wrapped app ({type(self.app)}) does. \",\n f\"If you are calling a {type(self.app)} method, retrieve it from that app instead of from `TruCustomApp`. \"\n )\n else:\n raise RuntimeError(\n f\"TruCustomApp nor wrapped app have attribute named {__name}.\"\n )\n\n def main_call(self, human: str):\n if self.main_method_loaded is None:\n raise RuntimeError(\n \"`main_method` was not specified so we do not know how to run this app.\"\n )\n\n sig = signature(self.main_method_loaded)\n bindings = sig.bind(self.app, human) # self.app is app's \"self\"\n\n return self.main_method_loaded(*bindings.args, **bindings.kwargs)\n\n\"\"\"\n # Async work ongoing:\n async def main_acall(self, human: str):\n # TODO: work in progress\n\n # must return an async generator of tokens/pieces that can be appended to create the full response\n\n if self.main_async_method is None:\n raise RuntimeError(\n \"`main_async_method` was not specified so we do not know how to run this app.\"\n )\n\n sig = signature(self.main_async_method)\n bindings = sig.bind(self.app, human) # self.app is app's \"self\"\n\n generator = await self.main_async_method(*bindings.args, **bindings.kwargs)\n\n return generator\n \"\"\"\n
"},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app.TruCustomApp.__init__","title":"
__init__(app, methods_to_instrument=None, **kwargs)","text":"
Wrap a custom class for recording.
- app: Any -- the custom app object being wrapped.
- More args in App
- More args in AppDefinition
- More args in WithClassInfo
Source code in
trulens_eval/trulens_eval/tru_custom_app.py def __init__(self, app: Any, methods_to_instrument=None, **kwargs):\n\"\"\"\n Wrap a custom class for recording.\n\n Arguments:\n - app: Any -- the custom app object being wrapped.\n - More args in App\n - More args in AppDefinition\n - More args in WithClassInfo\n \"\"\"\n\n kwargs['app'] = app\n kwargs['root_class'] = Class.of_object(app)\n\n instrument = Instrument(\n app=self # App mixes in WithInstrumentCallbacks\n )\n kwargs['instrument'] = instrument\n\n if 'main_method' in kwargs:\n main_method = kwargs['main_method']\n\n # TODO: ARGPARSE\n if isinstance(main_method, dict):\n main_method = Function(**main_method)\n\n if isinstance(main_method, Function):\n main_method_loaded = main_method.load()\n main_name = main_method.name\n\n cls = main_method.cls.load()\n mod = main_method.module.load().__name__\n\n else:\n main_name = main_method.__name__\n main_method_loaded = main_method\n\n if not safe_hasattr(main_method_loaded, \"__self__\"):\n raise ValueError(\n \"Please specify `main_method` as a bound method (like `someapp.somemethod` instead of `Someclass.somemethod`).\"\n )\n\n app_self = main_method_loaded.__self__\n\n assert app_self == app, \"`main_method`'s bound self must be the same as `app`.\"\n\n cls = app_self.__class__\n mod = cls.__module__\n\n instrument.include_modules.add(mod)\n instrument.include_classes.add(cls)\n instrument.include_methods[main_name] = lambda o: isinstance(o, cls)\n\n # This does instrumentation:\n super().__init__(**kwargs)\n\n # Needed to split this part to after the instrumentation so that the\n # getattr below gets the instrumented version of main method.\n if 'main_method' in kwargs:\n # Set main_method to the unbound version. Will be passing in app for\n # \"self\" manually when needed.\n main_method_loaded = getattr(cls, main_name)\n\n # This will be serialized as part of this TruCustomApp. Importatly, it is unbound.\n main_method = Function.of_function(main_method_loaded, cls=cls)\n\n self.main_method = main_method\n self.main_method_loaded = main_method_loaded\n\n methods_to_instrument = methods_to_instrument or dict()\n\n # The rest of this code instruments methods explicitly passed to\n # constructor as needing instrumentation and checks that methods\n # decorated with @instrument or passed explicitly belong to some\n # component as per serialized version of this app. If they are not,\n # placeholders are made in `app_extra_json` so that subsequent\n # serialization looks like the components exist.\n json = self.dict()\n\n for m, path in methods_to_instrument.items():\n method_name = m.__name__\n\n full_path = JSONPath().app + path\n\n self.instrument.instrument_method(\n method_name=method_name, obj=m.__self__, query=full_path\n )\n\n # TODO: DEDUP with next condition\n\n # Check whether the path/location of the method is in json serialization and\n # if not, add a placeholder to app_extra_json.\n try:\n next(full_path(json))\n\n print(\n f\"{UNICODE_CHECK} Added method {m.__name__} under component at path {full_path}\"\n )\n\n except Exception:\n logger.warning(\n f\"App has no component at path {full_path} . \"\n f\"Specify the component with the `app_extra_json` argument to TruCustomApp constructor. \"\n f\"Creating a placeholder there for now.\"\n )\n\n path.set(\n self.app_extra_json, {\n PLACEHOLDER:\n \"I was automatically added to `app_extra_json` because there was nothing here to refer to an instrumented method owner.\",\n m.__name__:\n f\"Placeholder for method {m.__name__}.\"\n }\n )\n\n # Check that any functions marked with `TruCustomApp.instrument` has been\n # instrumented as a method under some object.\n for f in TruCustomApp.functions_to_instrument:\n obj_ids_methods_and_full_paths = list(self._get_methods_for_func(f))\n\n if len(obj_ids_methods_and_full_paths) == 0:\n logger.warning(\n f\"Function {f} was not found during instrumentation walk. \"\n f\"Make sure it is accessible by traversing app {app} \"\n f\"or provide a bound method for it as TruCustomApp constructor argument `methods_to_instrument`.\"\n )\n\n else:\n for obj_id, m, full_path in obj_ids_methods_and_full_paths:\n try:\n next(full_path.get(json))\n\n except Exception as e:\n logger.warning(\n f\"App has no component owner of instrumented method {m} at path {full_path}. \"\n f\"Specify the component with the `app_extra_json` argument to TruCustomApp constructor. \"\n f\"Creating a placeholder there for now.\"\n )\n\n path.set(\n self.app_extra_json, {\n PLACEHOLDER:\n \"I was automatically added to `app_extra_json` because there was nothing here to refer to an instrumented method owner.\",\n m.__name__:\n f\"Placeholder for method {m.__name__}.\"\n }\n )\n\n # DB stuff and checks:\n self.post_init()\n
"},{"location":"trulens_eval/api/trucustom/#trulens_eval.trulens_eval.tru_custom_app.instrument","title":"
instrument","text":"
Bases: base_instrument
Decorator for marking methods to be instrumented in custom classes that are wrapped by TruCustomApp.
Source code in
trulens_eval/trulens_eval/tru_custom_app.py class instrument(base_instrument):\n\"\"\"\n Decorator for marking methods to be instrumented in custom classes that are\n wrapped by TruCustomApp.\n \"\"\"\n\n @classmethod\n def method(self_class, cls: type, name: str) -> None:\n base_instrument.method(cls, name)\n\n # Also make note of it for verification that it was found by the walk\n # after init.\n TruCustomApp.functions_to_instrument.add(getattr(cls, name))\n
"},{"location":"trulens_eval/api/trullama/","title":"Tru Llama","text":""},{"location":"trulens_eval/api/trullama/#trulens_eval.trulens_eval.tru_llama--llama_index-instrumentation-and-monitoring","title":"Llama_index instrumentation and monitoring.","text":""},{"location":"trulens_eval/api/trullama/#trulens_eval.trulens_eval.tru_llama.TruLlama","title":"
TruLlama","text":"
Bases: App
Instantiates the LLama Index Wrapper.
**Usage:**\n\nLLama-Index code: [LLama Index Quickstart](https://gpt-index.readthedocs.io/en/stable/getting_started/starter_example.html)\n```python\n # Code snippet taken from llama_index 0.8.15 (API subject to change with new versions)\nfrom llama_index import VectorStoreIndex, SimpleWebPageReader\n\ndocuments = SimpleWebPageReader(\n html_to_text=True\n).load_data([\"http://paulgraham.com/worked.html\"])\nindex = VectorStoreIndex.from_documents(documents)\n\nquery_engine = index.as_query_engine()\n```\n\nTrulens Eval Code:\n```python\nfrom trulens_eval import TruLlama\n# f_lang_match, f_qa_relevance, f_qs_relevance are feedback functions\ntru_recorder = TruLlama(query_engine,\n app_id='LlamaIndex_App1',\n feedbacks=[f_lang_match, f_qa_relevance, f_qs_relevance])\n\nwith tru_recorder as recording:\n query_engine.query(\"What is llama index?\")\n\ntru_record = recording.records[0]\n\n# To add record metadata \nwith tru_recorder as recording:\n recording.record_metadata=\"this is metadata for all records in this context that follow this line\"\n query_engine.query(\"What is llama index?\")\n recording.record_metadata=\"this is different metadata for all records in this context that follow this line\"\n query_engine.query(\"Where do I download llama index?\")\n\n```\n\nSee [Feedback Functions](https://www.trulens.org/trulens_eval/api/feedback/) for instantiating feedback functions.\n\nArgs:\n app (BaseQueryEngine | BaseChatEngine): A llama index application.\n
Source code in
trulens_eval/trulens_eval/tru_llama.py class TruLlama(App):\n\"\"\"\n Instantiates the LLama Index Wrapper.\n\n **Usage:**\n\n LLama-Index code: [LLama Index Quickstart](https://gpt-index.readthedocs.io/en/stable/getting_started/starter_example.html)\n ```python\n # Code snippet taken from llama_index 0.8.15 (API subject to change with new versions)\n from llama_index import VectorStoreIndex, SimpleWebPageReader\n\n documents = SimpleWebPageReader(\n html_to_text=True\n ).load_data([\"http://paulgraham.com/worked.html\"])\n index = VectorStoreIndex.from_documents(documents)\n\n query_engine = index.as_query_engine()\n ```\n\n Trulens Eval Code:\n ```python\n from trulens_eval import TruLlama\n # f_lang_match, f_qa_relevance, f_qs_relevance are feedback functions\n tru_recorder = TruLlama(query_engine,\n app_id='LlamaIndex_App1',\n feedbacks=[f_lang_match, f_qa_relevance, f_qs_relevance])\n\n with tru_recorder as recording:\n query_engine.query(\"What is llama index?\")\n\n tru_record = recording.records[0]\n\n # To add record metadata \n with tru_recorder as recording:\n recording.record_metadata=\"this is metadata for all records in this context that follow this line\"\n query_engine.query(\"What is llama index?\")\n recording.record_metadata=\"this is different metadata for all records in this context that follow this line\"\n query_engine.query(\"Where do I download llama index?\")\n\n ```\n\n See [Feedback Functions](https://www.trulens.org/trulens_eval/api/feedback/) for instantiating feedback functions.\n\n Args:\n app (BaseQueryEngine | BaseChatEngine): A llama index application.\n \"\"\"\n\n class Config:\n arbitrary_types_allowed = True\n\n app: Union[BaseQueryEngine, BaseChatEngine]\n\n root_callable: ClassVar[FunctionOrMethod] = Field(\n default_factory=lambda: FunctionOrMethod.of_callable(TruLlama.query),\n const=True\n )\n\n def __init__(self, app: Union[BaseQueryEngine, BaseChatEngine], **kwargs):\n super().update_forward_refs()\n\n # TruLlama specific:\n kwargs['app'] = app\n kwargs['root_class'] = Class.of_object(app) # TODO: make class property\n kwargs['instrument'] = LlamaInstrument(app=self)\n\n super().__init__(**kwargs)\n\n self.post_init()\n\n @classmethod\n def select_source_nodes(cls) -> JSONPath:\n\"\"\"\n Get the path to the source nodes in the query output.\n \"\"\"\n return cls.select_outputs().source_nodes[:]\n\n def main_input(\n self, func: Callable, sig: Signature, bindings: BoundArguments\n ) -> str:\n\"\"\"\n Determine the main input string for the given function `func` with\n signature `sig` if it is to be called with the given bindings\n `bindings`.\n \"\"\"\n\n if 'str_or_query_bundle' in bindings.arguments:\n # llama_index specific\n return bindings.arguments['str_or_query_bundle']\n\n elif 'message' in bindings.arguments:\n # llama_index specific\n return bindings.arguments['message']\n\n else:\n\n return App.main_input(self, func, sig, bindings)\n\n def main_output(\n self, func: Callable, sig: Signature, bindings: BoundArguments, ret: Any\n ) -> Optional[str]:\n\"\"\"\n Determine the main out string for the given function `func` with\n signature `sig` after it is called with the given `bindings` and has\n returned `ret`.\n \"\"\"\n\n try:\n attr = self._main_output_attribute(ret)\n\n if attr is not None:\n return getattr(ret, attr)\n else: # attr is None\n return App.main_output(self, func, sig, bindings, ret)\n\n except NotImplementedError:\n return None\n\n def _main_output_attribute(self, ret: Any) -> Optional[str]:\n\"\"\"\n Which attribute in ret contains the main output of this llama_index app.\n \"\"\"\n\n if isinstance(ret, Response): # query, aquery\n return \"response\"\n\n elif isinstance(ret, AgentChatResponse): # chat, achat\n return \"response\"\n\n elif isinstance(ret, (StreamingResponse, StreamingAgentChatResponse)):\n raise NotImplementedError(\n \"App produced a streaming response. \"\n \"Tracking content of streams in llama_index is not yet supported. \"\n \"App main_output will be None.\"\n )\n\n return None\n\n def main_call(self, human: str):\n # If available, a single text to a single text invocation of this app.\n\n if isinstance(self.app, BaseQueryEngine):\n ret = self.app.query(human)\n elif isinstance(self.app, BaseChatEngine):\n ret = self.app.chat(human)\n else:\n raise RuntimeError(\n f\"Do not know what the main method for app of type {type(self.app).__name__} is.\"\n )\n\n try:\n attr = self._main_output_attribute(ret)\n assert attr is not None\n return getattr(ret, attr)\n\n except Exception:\n raise NotImplementedError(\n f\"Do not know what in object of type {type(ret).__name__} is the main app output.\"\n )\n\n async def main_acall(self, human: str):\n # If available, a single text to a single text invocation of this app.\n\n if isinstance(self.app, BaseQueryEngine):\n ret = await self.app.aquery(human)\n elif isinstance(self.app, BaseChatEngine):\n ret = await self.app.achat(human)\n else:\n raise RuntimeError(\n f\"Do not know what the main async method for app of type {type(self.app).__name__} is.\"\n )\n\n try:\n attr = self._main_output_attribute(ret)\n assert attr is not None\n return getattr(ret, attr)\n\n except Exception:\n raise NotImplementedError(\n f\"Do not know what in object of type {type(ret).__name__} is the main app output.\"\n )\n\n # TODEP\n # llama_index.chat_engine.types.BaseChatEngine\n def chat(self, *args, **kwargs) -> AgentChatResponse:\n assert isinstance(self.app, BaseChatEngine)\n\n self._with_dep_message(method=\"chat\", is_async=False, with_record=False)\n\n res, _ = self.chat_with_record(*args, **kwargs)\n return res\n\n # TODEP\n # llama_index.chat_engine.types.BaseChatEngine\n async def achat(self, *args, **kwargs) -> AgentChatResponse:\n assert isinstance(self.app, BaseChatEngine)\n\n self._with_dep_message(method=\"achat\", is_async=True, with_record=False)\n\n res, _ = await self.achat_with_record(*args, **kwargs)\n return res\n\n # TODEP\n # llama_index.chat_engine.types.BaseChatEngine\n def stream_chat(self, *args, **kwargs) -> StreamingAgentChatResponse:\n assert isinstance(self.app, BaseChatEngine)\n\n self._with_dep_message(\n method=\"stream_chat\", is_async=False, with_record=False\n )\n\n res, _ = self.stream_chat_with_record(*args, **kwargs)\n return res\n\n # TODEP\n # llama_index.chat_engine.types.BaseChatEngine\n async def astream_chat(self, *args, **kwargs) -> StreamingAgentChatResponse:\n assert isinstance(self.app, BaseChatEngine)\n\n self._with_dep_message(\n method=\"astream_chat\", is_async=True, with_record=False\n )\n\n res, _ = await self.astream_chat_with_record(*args, **kwargs)\n return res\n\n # TODEP\n # llama_index.indices.query.base.BaseQueryEngine\n def query(self, *args, **kwargs) -> RESPONSE_TYPE:\n\n assert isinstance(self.app, BaseQueryEngine)\n\n self._with_dep_message(\n method=\"query\", is_async=False, with_record=False\n )\n\n res, _ = self.query_with_record(*args, **kwargs)\n return res\n\n # TODEP\n # llama_index.indices.query.base.BaseQueryEngine\n async def aquery(self, *args, **kwargs) -> RESPONSE_TYPE:\n\n assert isinstance(self.app, BaseQueryEngine)\n\n self._with_dep_message(\n method=\"aquery\", is_async=True, with_record=False\n )\n\n res, _ = await self.aquery_with_record(*args, **kwargs)\n return res\n\n # TODEP\n # Mirrors llama_index.indices.query.base.BaseQueryEngine.query .\n def query_with_record(self, *args,\n **kwargs) -> Tuple[RESPONSE_TYPE, Record]:\n\n assert isinstance(self.app, BaseQueryEngine)\n\n self._with_dep_message(method=\"query\", is_async=False, with_record=True)\n\n return self.with_record(self.app.query, *args, **kwargs)\n\n # TODEP\n # Mirrors llama_index.indices.query.base.BaseQueryEngine.aquery .\n async def aquery_with_record(self, *args,\n **kwargs) -> Tuple[RESPONSE_TYPE, Record]:\n assert isinstance(self.app, BaseQueryEngine)\n\n self._with_dep_message(method=\"aquery\", is_async=True, with_record=True)\n\n return await self.awith_record(self.app.aquery, *args, **kwargs)\n\n # TODEP\n # Compatible with llama_index.chat_engine.types.BaseChatEngine.chat .\n def chat_with_record(self, *args,\n **kwargs) -> Tuple[AgentChatResponse, Record]:\n\n assert isinstance(self.app, BaseChatEngine)\n\n self._with_dep_message(method=\"chat\", is_async=False, with_record=True)\n\n return self.with_record(self.app.chat, *args, **kwargs)\n\n # TODEP\n # Compatible with llama_index.chat_engine.types.BaseChatEngine.achat .\n async def achat_with_record(self, *args,\n **kwargs) -> Tuple[AgentChatResponse, Record]:\n assert isinstance(self.app, BaseChatEngine)\n\n self._with_dep_message(method=\"achat\", is_async=True, with_record=True)\n\n return await self.awith_record(self.app.achat, *args, **kwargs)\n\n # TODEP\n # Compatible with llama_index.chat_engine.types.BaseChatEngine.stream_chat .\n def stream_chat_with_record(\n self, *args, **kwargs\n ) -> Tuple[StreamingAgentChatResponse, Record]:\n\n assert isinstance(self.app, BaseChatEngine)\n\n self._with_dep_message(\n method=\"stream\", is_async=False, with_record=True\n )\n\n return self.with_record(self.app.stream_chat, *args, **kwargs)\n\n # TODEP\n # Compatible with llama_index.chat_engine.types.BaseChatEngine.astream_chat .\n async def astream_chat_with_record(\n self, *args, **kwargs\n ) -> Tuple[StreamingAgentChatResponse, Record]:\n\n assert isinstance(self.app, BaseChatEngine)\n\n self._with_dep_message(\n method=\"astream_chat\", is_async=True, with_record=True\n )\n\n return await self.awith_record(self.app.astream_chat, *args, **kwargs)\n
"},{"location":"trulens_eval/api/trullama/#trulens_eval.trulens_eval.tru_llama.TruLlama.main_input","title":"
main_input(func, sig, bindings)","text":"
Determine the main input string for the given function func with signature sig if it is to be called with the given bindings bindings.
Source code in
trulens_eval/trulens_eval/tru_llama.py def main_input(\n self, func: Callable, sig: Signature, bindings: BoundArguments\n) -> str:\n\"\"\"\n Determine the main input string for the given function `func` with\n signature `sig` if it is to be called with the given bindings\n `bindings`.\n \"\"\"\n\n if 'str_or_query_bundle' in bindings.arguments:\n # llama_index specific\n return bindings.arguments['str_or_query_bundle']\n\n elif 'message' in bindings.arguments:\n # llama_index specific\n return bindings.arguments['message']\n\n else:\n\n return App.main_input(self, func, sig, bindings)\n
"},{"location":"trulens_eval/api/trullama/#trulens_eval.trulens_eval.tru_llama.TruLlama.main_output","title":"
main_output(func, sig, bindings, ret)","text":"
Determine the main out string for the given function func with signature sig after it is called with the given bindings and has returned ret.
Source code in
trulens_eval/trulens_eval/tru_llama.py def main_output(\n self, func: Callable, sig: Signature, bindings: BoundArguments, ret: Any\n) -> Optional[str]:\n\"\"\"\n Determine the main out string for the given function `func` with\n signature `sig` after it is called with the given `bindings` and has\n returned `ret`.\n \"\"\"\n\n try:\n attr = self._main_output_attribute(ret)\n\n if attr is not None:\n return getattr(ret, attr)\n else: # attr is None\n return App.main_output(self, func, sig, bindings, ret)\n\n except NotImplementedError:\n return None\n
"},{"location":"trulens_eval/api/trullama/#trulens_eval.trulens_eval.tru_llama.TruLlama.select_source_nodes","title":"
select_source_nodes() classmethod","text":"
Get the path to the source nodes in the query output.
Source code in
trulens_eval/trulens_eval/tru_llama.py @classmethod\ndef select_source_nodes(cls) -> JSONPath:\n\"\"\"\n Get the path to the source nodes in the query output.\n \"\"\"\n return cls.select_outputs().source_nodes[:]\n
"},{"location":"trulens_explain/attribution_parameterization/","title":"Attributions","text":""},{"location":"trulens_explain/attribution_parameterization/#attribution-parameterization","title":"Attribution Parameterization","text":"
Attributions for different models and use cases can range from simple to more complex. This page provides guidelines on how to set various attribution parameters to achieve your LLM explainability goals.
"},{"location":"trulens_explain/attribution_parameterization/#basic-definitions-and-terminology","title":"Basic Definitions and Terminology","text":"
What is a tensor? A tensor is a multidimensional object that can be model inputs, or layer activations.
What is a layer? A layer is a set of neurons that can be thought of as a function on input tensors. Layer inputs are tensors. Layer outputs are modified tensors.
What are anchors? Anchors are ways of specifying which tensors you want. You may want the input tensor of a layer, or the output tensor of a layer.
E.g. Say you have a concat layer and you want to explain the 2 concatenated tensors. The concat operation is not usually a layer tracked by the model. If you try the 'in' anchor of the layer after the operation, you get a single tensor with all the information you need.
What is a Quantity of Interest (QoI)? A QoI is a scalar number that is being explained.
E.g. With saliency maps, you get dx/dy (i.e. the effect of input on output). y in this case is the QoI scalar. It is usually the output of a neuron, but could be a sum of multiple neurons.
What is an attribution? An attribution is a numerical value associated with every element in a tensor that explains a QoI.
E.g. With saliency maps, you get dx/dy. x is the associated tensor. The entirety of dx/dy is the explanation.
What are cuts? Cuts are tensors that cut a network into two parts. They are composed of a layer and an anchor.
What are slices? Slices are two cuts leaving a slice of the network. The attribution will be on the first cut, explaining the QoI on the second cut of the slice.
E.g. With saliency maps, the TruLens slice would be AttributionCut: Cut(x) to QoICut: Cut(y), denoted by Slice(Cut(x),Cut(y)).
"},{"location":"trulens_explain/attribution_parameterization/#how-to-use-trulens","title":"How to use TruLens?","text":"
This section will cover different use cases from the most basic to the most complex. For the following use cases, it may help to refer to Summary.
"},{"location":"trulens_explain/attribution_parameterization/#case-1-input-output-cut-basic-configuration","title":"Case 1: Input-Output cut (Basic configuration)","text":"
Use case: Explain the input given the output. Cuts needed: TruLens defaults. Attribution Cut (The tensor we would like to assign importance) \u2192 InputCut (model args / kwargs) QoI Cut (The tensor that we are interested to explain) \u2192 OutputCut
"},{"location":"trulens_explain/attribution_parameterization/#case-2-the-qoi-cut","title":"Case 2: The QoI Cut","text":"
Now suppose you want to explain some internal (intermediate) layer\u2019s output (i.e. how the input is affecting the output at some intermediate layer).
Use case: Explain something that isn't the default model output.
E.g. If you want to explain a logit layer instead of the probit (final) layer.
Cuts needed: As you want to explain something different than the default output, you need to change the QoI from the default to the layer that you are interested. Attribution Cut \u2192 InputCut QoI Cut \u2192 Your logit layer, anchor:'out'
"},{"location":"trulens_explain/attribution_parameterization/#case-3-the-attribution-cut","title":"Case 3: The Attribution Cut","text":"
Now suppose you want to know the attribution of some internal layer on the final output.
Use cases:
- As a preprocessing step, you drop a feature, so do not need attributions on that.
- For PyTorch models, model inputs are not tensors, so you'd want the 'in' anchor of the first layer.
Cuts needed: As you want to know the affect of some other layer rather than the input layer, you need to customize the attribution cut. Model inputs \u2192 InputCut Attribution Cut \u2192 Your attribution layer (The layer you want to assign importance/attributions with respect to output), anchor:'in' QoI Cut \u2192 OutputCut
"},{"location":"trulens_explain/attribution_parameterization/#advanced-use-cases","title":"Advanced Use Cases","text":"
For the following use cases, it may help to refer to Advanced Definitions.
"},{"location":"trulens_explain/attribution_parameterization/#case-4-the-distribution-of-interest-doi-cut-explanation-flexibility","title":"Case 4: The Distribution of Interest (DoI) Cut / Explanation flexibility","text":"
Usually, we explain the output with respect to each point in the input. All cases up to now were using a default called PointDoI. Now, suppose you want to explain using an aggregate over samples of points.
Use case: You want to perform approaches like Integrated Gradients, Grad-CAM, Shapley values instead of saliency maps. These only differ by sampling strategies.
E.g. Integrated Gradients is a sample from a straight line from a baseline to a value.
Cuts needed: Define a DoI that samples from the default attribution cut. Model inputs \u2192 InputCut DoI/Attribution Cut \u2192 Your baseline/DoI/attribution layer, anchor:'in' QoI Cut \u2192 OutputCut
"},{"location":"trulens_explain/attribution_parameterization/#case-5-internal-explanations","title":"Case 5: Internal explanations","text":"
Use case: You want to explain an internal layer. Methods like Integrated Gradients are a DoI on the baseline to the value, but it is located on the layer the baseline is defined. If you want to explain an internal layer, you do not move the DoI layer. Cuts needed: Attribution layer different from DoI. Model inputs \u2192 InputCut DoI Cut \u2192 Your baseline/DoI layer, anchor:'in' Attribution Cut \u2192 Your internal attribution layer, anchor:'out' or 'in' QoI Cut \u2192 OutputCut
"},{"location":"trulens_explain/attribution_parameterization/#case-6-your-baseline-happens-at-a-different-layer-than-your-sampling","title":"Case 6: Your baseline happens at a different layer than your sampling.","text":"
Use Case: in NLP, baselines are tokens, but the interpolation is on the embedding layer. Cuts needed: Baseline different from DoI. Model inputs \u2192 InputCut Baseline Cut \u2192 Tokens, anchor:'out' DoI/Attribution Cut \u2192 Embeddings, anchor:'out' QoI Cut \u2192 OutputCut
"},{"location":"trulens_explain/attribution_parameterization/#case-7-putting-it-together-the-most-complex-case-we-can-perform-with-trulens","title":"Case 7: Putting it together - The most complex case we can perform with TruLens","text":"
Use Case: Internal layer explanations of NLP, on the logit layer of a model with probit outputs. Model inputs \u2192 InputCut Baseline Cut \u2192 Tokens, anchor:'out' DoI Cut \u2192 Embeddings, anchor:'out' Attribution Cut \u2192 Internal layer, anchor:'out' QoI Cut \u2192 Logit layer, anchor:'out'
"},{"location":"trulens_explain/attribution_parameterization/#summary","title":"Summary","text":"
InputCut is model args / kwargs. OutputCut is the model output.
Baseline Cut is the tensor associated with the Integrated Gradients baseline. Can be the InputCut or later. DoI Cut is the tensor associated with explanation sampling. Can be the BaselineCut or later. Attribution Cut is the tensor that should be explained. Can be the DoICut or later. QoI Cut is what is being explained with a QoI. Must be after the AttributionCut.
"},{"location":"trulens_explain/attribution_parameterization/#advanced-definitions","title":"Advanced Definitions","text":"
What is a Distribution of Interest (DoI)?
The distribution of interest is a concept of aggregating attributions over a sample or distribution.
- Grad-CAM (Paper, GitHub, Docs) does this over a Gaussian distribution of inputs.
- Shapley values (GitHub, Docs) do this over different background data.
- Integrated Gradients (Paper, Tutorial) do this over an interpolation from a baseline to the input.
How does this relate to the Attribution Cut?
The sample or distributions are taken at a place that is humanly considered the input, even if this differs from the programmatic model input.
For attributions, all parts of a network can have an attribution towards the QoI. The most common use case is to explain the tensors that are also humanly considered the input (which is where the DoI occurs).
How does this relate to the Baseline Cut?
The Baseline Cut is only applicable to the Integrated Gradients method. It is also only needed when there is no mathematical way to interpolate the baseline to the input.
E.g. if the input is 'Hello', but the baseline is a '[MASK]' token, we cannot interpolate that. We define the baseline at the token layer, but interpolate on a numeric layer like the embeddings.
"},{"location":"trulens_explain/gh_top_intro/","title":"Gh top intro","text":""},{"location":"trulens_explain/gh_top_intro/#trulens-explain","title":"TruLens-Explain","text":"
TruLens-Explain is a cross-framework library for deep learning explainability. It provides a uniform abstraction over a number of different frameworks. It provides a uniform abstraction layer over TensorFlow, Pytorch, and Keras and allows input and internal explanations.
"},{"location":"trulens_explain/gh_top_intro/#installation-and-setup","title":"Installation and Setup","text":"
These installation instructions assume that you have conda installed and added to your path.
-
Create a virtual environment (or modify an existing one).
conda create -n \"<my_name>\" python=3 # Skip if using existing environment.\nconda activate <my_name>\n
-
Install dependencies.
conda install tensorflow-gpu=1 # Or whatever backend you're using.\nconda install keras # Or whatever backend you're using.\nconda install matplotlib # For visualizations.\n
-
[Pip installation] Install the trulens pip package from PyPI.
pip install trulens\n
"},{"location":"trulens_explain/gh_top_intro/#quick-usage","title":"Quick Usage","text":"
To quickly play around with the TruLens library, check out the following Colab notebooks:
- PyTorch:
- TensorFlow 2 / Keras:
For more information, see TruLens-Explain Documentation.
"},{"location":"trulens_explain/install/","title":"\ud83d\ude80 Installation","text":""},{"location":"trulens_explain/install/#getting-access-to-trulens","title":"Getting access to TruLens","text":"
These installation instructions assume that you have conda installed and added to your path.
-
Create a virtual environment (or modify an existing one).
conda create -n \"<my_name>\" python=3.7 # Skip if using existing environment.\nconda activate <my_name>\n
-
Install dependencies.
conda install tensorflow-gpu=1 # Or whatever backend you're using.\nconda install keras # Or whatever backend you're using.\nconda install matplotlib # For visualizations.\n
-
[Pip installation] Install the trulens pip package from PyPI.
pip install trulens\n
-
[Local installation] If you would like to develop or modify TruLens, you can download the source code by cloning the TruLens repo.
git clone https://github.com/truera/trulens.git\n
-
[Local installation] Install the TruLens repo.
cd trulens_explain\npip install -e .\n
"},{"location":"trulens_explain/quickstart/","title":"\u26a1 Quickstart","text":""},{"location":"trulens_explain/quickstart/#quickstart","title":"Quickstart","text":""},{"location":"trulens_explain/quickstart/#playground","title":"Playground","text":"
To quickly play around with the TruLens library, check out the following Colab notebooks:
- PyTorch:
- TensorFlow 2 / Keras:
"},{"location":"trulens_explain/quickstart/#install-use","title":"Install & Use","text":"
Check out the Installation instructions for information on how to install the library, use it, and contribute.
"},{"location":"trulens_explain/api/attribution/","title":"Attribution Methods","text":"
Attribution methods quantitatively measure the contribution of each of a function's individual inputs to its output. Gradient-based attribution methods compute the gradient of a model with respect to its inputs to describe how important each input is towards the output prediction. These methods can be applied to assist in explaining deep networks.
TruLens provides implementations of several such techniques, found in this package.
"},{"location":"trulens_explain/api/attribution/#trulens_explain.trulens.nn.attribution.AttributionMethod","title":"
AttributionMethod","text":"
Bases: AbstractBaseClass
Interface used by all attribution methods.
An attribution method takes a neural network model and provides the ability to assign values to the variables of the network that specify the importance of each variable towards particular predictions.
Source code in
trulens_explain/trulens/nn/attribution.py class AttributionMethod(AbstractBaseClass):\n\"\"\"\n Interface used by all attribution methods.\n\n An attribution method takes a neural network model and provides the ability\n to assign values to the variables of the network that specify the importance\n of each variable towards particular predictions.\n \"\"\"\n\n @abstractmethod\n def __init__(\n self, model: ModelWrapper, rebatch_size: int = None, *args, **kwargs\n ):\n\"\"\"\n Abstract constructor.\n\n Parameters:\n model: ModelWrapper\n Model for which attributions are calculated.\n\n rebatch_size: int (optional)\n Will rebatch instances to this size if given. This may be\n required for GPU usage if using a DoI which produces multiple\n instances per user-provided instance. Many valued DoIs will\n expand the tensors sent to each layer to original_batch_size *\n doi_size. The rebatch size will break up original_batch_size *\n doi_size into rebatch_size chunks to send to model.\n \"\"\"\n self._model = model\n\n self.rebatch_size = rebatch_size\n\n @property\n def model(self) -> ModelWrapper:\n\"\"\"\n Model for which attributions are calculated.\n \"\"\"\n return self._model\n\n @abstractmethod\n def _attributions(self, model_inputs: ModelInputs) -> AttributionResult:\n\"\"\"\n For attributions that have options to return multiple things depending\n on configuration, wrap those multiple things in the AttributionResult\n tuple.\n \"\"\"\n ...\n\n def attributions(\n self, *model_args: ArgsLike, **model_kwargs: KwargsLike\n ) -> Union[TensorLike, ArgsLike[TensorLike],\n ArgsLike[ArgsLike[TensorLike]]]:\n\"\"\"\n Returns attributions for the given input. Attributions are in the same\n shape as the layer that attributions are being generated for. \n\n The numeric scale of the attributions will depend on the specific\n implementations of the Distribution of Interest and Quantity of\n Interest. However it is generally related to the scale of gradients on\n the Quantity of Interest. \n\n For example, Integrated Gradients uses the linear interpolation\n Distribution of Interest which subsumes the completeness axiom which\n ensures the sum of all attributions of a record equals the output\n determined by the Quantity of Interest on the same record. \n\n The Point Distribution of Interest will be determined by the gradient at\n a single point, thus being a good measure of model sensitivity. \n\n Parameters:\n model_args: ArgsLike, model_kwargs: KwargsLike\n The args and kwargs given to the call method of a model. This\n should represent the records to obtain attributions for, assumed\n to be a *batched* input. if `self.model` supports evaluation on\n *data tensors*, the appropriate tensor type may be used (e.g.,\n Pytorch models may accept Pytorch tensors in addition to\n `np.ndarray`s). The shape of the inputs must match the input\n shape of `self.model`. \n\n Returns\n - np.ndarray when single attribution_cut input, single qoi output\n - or ArgsLike[np.ndarray] when single input, multiple output (or\n vice versa) \n - or ArgsLike[ArgsLike[np.ndarray]] when multiple output (outer),\n multiple input (inner)\n\n An array of attributions, matching the shape and type of `from_cut`\n of the slice. Each entry in the returned array represents the degree\n to which the corresponding feature affected the model's outcome on\n the corresponding point.\n\n If attributing to a component with multiple inputs, a list for each\n will be returned.\n\n If the quantity of interest features multiple outputs, a list for\n each will be returned.\n \"\"\"\n\n # Calls like: attributions([arg1, arg2]) will get read as model_args =\n # ([arg1, arg2],), that is, a tuple with a single element containing the\n # model args. Test below checks for this. TODO: Disallow such\n # invocations? They should be given as attributions(arg1, arg2).\n if isinstance(model_args,\n tuple) and len(model_args) == 1 and isinstance(\n model_args[0], DATA_CONTAINER_TYPE):\n model_args = model_args[0]\n\n model_inputs = ModelInputs(\n args=many_of_om(model_args), kwargs=model_kwargs\n )\n # Will cast results to this data container type.\n return_type = type(model_inputs.first_batchable(get_backend()))\n\n pieces = self._attributions(model_inputs)\n\n # Format attributions into the public structure which throws out output\n # lists and input lists if there is only one output or only one input.\n # Also cast to whatever the input type was.\n attributions: Outputs[Inputs[np.ndarray]] = nested_cast(\n backend=get_backend(), astype=return_type, args=pieces.attributions\n )\n attributions: Outputs[OM[Inputs, np.ndarray]\n ] = [om_of_many(attr) for attr in attributions]\n attributions: OM[Outputs, OM[Inputs,\n np.ndarray]] = om_of_many(attributions)\n\n if pieces.gradients is not None or pieces.interventions is not None:\n tru_logger.warning(\n \"AttributionMethod configured to return gradients or interventions. \"\n \"Use the internal _attribution call to retrieve those.\"\n )\n\n return attributions\n
"},{"location":"trulens_explain/api/attribution/#trulens_explain.trulens.nn.attribution.AttributionMethod.model","title":"
model: ModelWrapper property","text":"
Model for which attributions are calculated.
"},{"location":"trulens_explain/api/attribution/#trulens_explain.trulens.nn.attribution.AttributionMethod.__init__","title":"
__init__(model, rebatch_size=None, *args, **kwargs) abstractmethod","text":"
Abstract constructor.
Parameters:
Name Type Description Default
model ModelWrapper ModelWrapper Model for which attributions are calculated.
required
rebatch_size int int (optional) Will rebatch instances to this size if given. This may be required for GPU usage if using a DoI which produces multiple instances per user-provided instance. Many valued DoIs will expand the tensors sent to each layer to original_batch_size * doi_size. The rebatch size will break up original_batch_size * doi_size into rebatch_size chunks to send to model.
None Source code in
trulens_explain/trulens/nn/attribution.py @abstractmethod\ndef __init__(\n self, model: ModelWrapper, rebatch_size: int = None, *args, **kwargs\n):\n\"\"\"\n Abstract constructor.\n\n Parameters:\n model: ModelWrapper\n Model for which attributions are calculated.\n\n rebatch_size: int (optional)\n Will rebatch instances to this size if given. This may be\n required for GPU usage if using a DoI which produces multiple\n instances per user-provided instance. Many valued DoIs will\n expand the tensors sent to each layer to original_batch_size *\n doi_size. The rebatch size will break up original_batch_size *\n doi_size into rebatch_size chunks to send to model.\n \"\"\"\n self._model = model\n\n self.rebatch_size = rebatch_size\n
"},{"location":"trulens_explain/api/attribution/#trulens_explain.trulens.nn.attribution.AttributionMethod.attributions","title":"
attributions(*model_args, **model_kwargs)","text":"
Returns attributions for the given input. Attributions are in the same shape as the layer that attributions are being generated for.
The numeric scale of the attributions will depend on the specific implementations of the Distribution of Interest and Quantity of Interest. However it is generally related to the scale of gradients on the Quantity of Interest.
For example, Integrated Gradients uses the linear interpolation Distribution of Interest which subsumes the completeness axiom which ensures the sum of all attributions of a record equals the output determined by the Quantity of Interest on the same record.
The Point Distribution of Interest will be determined by the gradient at a single point, thus being a good measure of model sensitivity.
Parameters:
Name Type Description Default
model_args ArgsLike ArgsLike, model_kwargs: KwargsLike The args and kwargs given to the call method of a model. This should represent the records to obtain attributions for, assumed to be a batched input. if self.model supports evaluation on data tensors, the appropriate tensor type may be used (e.g., Pytorch models may accept Pytorch tensors in addition to np.ndarrays). The shape of the inputs must match the input shape of self.model.
() Returns - np.ndarray when single attribution_cut input, single qoi output - or ArgsLike[np.ndarray] when single input, multiple output (or vice versa) - or ArgsLike[ArgsLike[np.ndarray]] when multiple output (outer), multiple input (inner)
An array of attributions, matching the shape and type of `from_cut`\nof the slice. Each entry in the returned array represents the degree\nto which the corresponding feature affected the model's outcome on\nthe corresponding point.\n\nIf attributing to a component with multiple inputs, a list for each\nwill be returned.\n\nIf the quantity of interest features multiple outputs, a list for\neach will be returned.\n
Source code in
trulens_explain/trulens/nn/attribution.py def attributions(\n self, *model_args: ArgsLike, **model_kwargs: KwargsLike\n) -> Union[TensorLike, ArgsLike[TensorLike],\n ArgsLike[ArgsLike[TensorLike]]]:\n\"\"\"\n Returns attributions for the given input. Attributions are in the same\n shape as the layer that attributions are being generated for. \n\n The numeric scale of the attributions will depend on the specific\n implementations of the Distribution of Interest and Quantity of\n Interest. However it is generally related to the scale of gradients on\n the Quantity of Interest. \n\n For example, Integrated Gradients uses the linear interpolation\n Distribution of Interest which subsumes the completeness axiom which\n ensures the sum of all attributions of a record equals the output\n determined by the Quantity of Interest on the same record. \n\n The Point Distribution of Interest will be determined by the gradient at\n a single point, thus being a good measure of model sensitivity. \n\n Parameters:\n model_args: ArgsLike, model_kwargs: KwargsLike\n The args and kwargs given to the call method of a model. This\n should represent the records to obtain attributions for, assumed\n to be a *batched* input. if `self.model` supports evaluation on\n *data tensors*, the appropriate tensor type may be used (e.g.,\n Pytorch models may accept Pytorch tensors in addition to\n `np.ndarray`s). The shape of the inputs must match the input\n shape of `self.model`. \n\n Returns\n - np.ndarray when single attribution_cut input, single qoi output\n - or ArgsLike[np.ndarray] when single input, multiple output (or\n vice versa) \n - or ArgsLike[ArgsLike[np.ndarray]] when multiple output (outer),\n multiple input (inner)\n\n An array of attributions, matching the shape and type of `from_cut`\n of the slice. Each entry in the returned array represents the degree\n to which the corresponding feature affected the model's outcome on\n the corresponding point.\n\n If attributing to a component with multiple inputs, a list for each\n will be returned.\n\n If the quantity of interest features multiple outputs, a list for\n each will be returned.\n \"\"\"\n\n # Calls like: attributions([arg1, arg2]) will get read as model_args =\n # ([arg1, arg2],), that is, a tuple with a single element containing the\n # model args. Test below checks for this. TODO: Disallow such\n # invocations? They should be given as attributions(arg1, arg2).\n if isinstance(model_args,\n tuple) and len(model_args) == 1 and isinstance(\n model_args[0], DATA_CONTAINER_TYPE):\n model_args = model_args[0]\n\n model_inputs = ModelInputs(\n args=many_of_om(model_args), kwargs=model_kwargs\n )\n # Will cast results to this data container type.\n return_type = type(model_inputs.first_batchable(get_backend()))\n\n pieces = self._attributions(model_inputs)\n\n # Format attributions into the public structure which throws out output\n # lists and input lists if there is only one output or only one input.\n # Also cast to whatever the input type was.\n attributions: Outputs[Inputs[np.ndarray]] = nested_cast(\n backend=get_backend(), astype=return_type, args=pieces.attributions\n )\n attributions: Outputs[OM[Inputs, np.ndarray]\n ] = [om_of_many(attr) for attr in attributions]\n attributions: OM[Outputs, OM[Inputs,\n np.ndarray]] = om_of_many(attributions)\n\n if pieces.gradients is not None or pieces.interventions is not None:\n tru_logger.warning(\n \"AttributionMethod configured to return gradients or interventions. \"\n \"Use the internal _attribution call to retrieve those.\"\n )\n\n return attributions\n
"},{"location":"trulens_explain/api/attribution/#trulens_explain.trulens.nn.attribution.AttributionResult","title":"
AttributionResult dataclass","text":"
_attribution method output container.
Source code in
trulens_explain/trulens/nn/attribution.py @dataclass\nclass AttributionResult:\n\"\"\"\n _attribution method output container.\n \"\"\"\n\n attributions: Outputs[Inputs[TensorLike]] = None\n gradients: Outputs[Inputs[Uniform[TensorLike]]] = None\n interventions: Inputs[Uniform[TensorLike]] = None\n
"},{"location":"trulens_explain/api/attribution/#trulens_explain.trulens.nn.attribution.InputAttribution","title":"
InputAttribution","text":"
Bases: InternalInfluence
Attributions of input features on either internal or output quantities. This is essentially an alias for
InternalInfluence(\n model,\n (trulens.nn.slices.InputCut(), cut),\n qoi,\n doi,\n multiply_activation)\n
Source code in
trulens_explain/trulens/nn/attribution.py class InputAttribution(InternalInfluence):\n\"\"\"\n Attributions of input features on either internal or output quantities. This\n is essentially an alias for\n\n ```python\n InternalInfluence(\n model,\n (trulens.nn.slices.InputCut(), cut),\n qoi,\n doi,\n multiply_activation)\n ```\n \"\"\"\n\n def __init__(\n self,\n model: ModelWrapper,\n qoi_cut: CutLike = None, # see WARNING-LOAD-INIT\n qoi: QoiLike = 'max',\n doi_cut: CutLike = None, # see WARNING-LOAD-INIT\n doi: DoiLike = 'point',\n multiply_activation: bool = True,\n *args,\n **kwargs\n ):\n\"\"\"\n Parameters:\n model :\n Model for which attributions are calculated.\n\n qoi_cut :\n The cut determining the layer from which the QoI is derived.\n Expects a `Cut` object, or a related type that can be\n interpreted as a `Cut`, as documented below.\n\n If an `int` is given, it represents the index of a layer in\n `model`. \n\n If a `str` is given, it represents the name of a layer in\n `model`. \n\n `None` is an alternative for `slices.OutputCut()`.\n\n qoi : quantities.QoI | int | tuple | str\n Quantity of interest to attribute. Expects a `QoI` object, or a\n related type that can be interpreted as a `QoI`, as documented\n below.\n\n If an `int` is given, the quantity of interest is taken to be\n the slice output for the class/neuron/channel specified by the\n given integer, i.e., ```python\n quantities.InternalChannelQoI(qoi) ```\n\n If a tuple or list of two integers is given, then the quantity\n of interest is taken to be the comparative quantity for the\n class given by the first integer against the class given by the\n second integer, i.e., ```python quantities.ComparativeQoI(*qoi)\n ```\n\n If a callable is given, it is interpreted as a function\n representing the QoI, i.e., ```python quantities.LambdaQoI(qoi)\n ```\n\n If the string, `'max'`, is given, the quantity of interest is\n taken to be the output for the class with the maximum score,\n i.e., ```python quantities.MaxClassQoI() ```\n\n doi_cut :\n For models which have non-differentiable pre-processing at the\n start of the model, specify the cut of the initial\n differentiable input form. For NLP models, for example, this\n could point to the embedding layer. If not provided, InputCut is\n assumed.\n\n doi : distributions.DoI | str\n Distribution of interest over inputs. Expects a `DoI` object, or\n a related type that can be interpreted as a `DoI`, as documented\n below.\n\n If the string, `'point'`, is given, the distribution is taken to\n be the single point passed to `attributions`, i.e., ```python\n distributions.PointDoi() ```\n\n If the string, `'linear'`, is given, the distribution is taken\n to be the linear interpolation from the zero input to the point\n passed to `attributions`, i.e., ```python\n distributions.LinearDoi() ```\n\n multiply_activation : bool, optional\n Whether to multiply the gradient result by its corresponding\n activation, thus converting from \"*influence space*\" to\n \"*attribution space*.\"\n \"\"\"\n if doi_cut is None:\n # WARNING-LOAD-INIT: Do not put this as a default arg in the def\n # line. That would cause an instantiation of InputCut when this\n # class is loaded and before it is used. Because get_backend gets\n # called in Cut.__init__, it may fail if this class is loaded before\n # trulens.nn.models.get_model_wrapper is called on some model.\n doi_cut = InputCut()\n\n super().__init__(\n model, (doi_cut, qoi_cut),\n qoi,\n doi,\n multiply_activation=multiply_activation,\n *args,\n **kwargs\n )\n
"},{"location":"trulens_explain/api/attribution/#trulens_explain.trulens.nn.attribution.InputAttribution.__init__","title":"
__init__(model, qoi_cut=None, qoi='max', doi_cut=None, doi='point', multiply_activation=True, *args, **kwargs)","text":"
Parameters:
Name Type Description Default
model Model for which attributions are calculated.
required
qoi_cut The cut determining the layer from which the QoI is derived. Expects a Cut object, or a related type that can be interpreted as a Cut, as documented below.
If an int is given, it represents the index of a layer in model.
If a str is given, it represents the name of a layer in model.
None is an alternative for slices.OutputCut().
None qoi quantities.QoI | int | tuple | str Quantity of interest to attribute. Expects a QoI object, or a related type that can be interpreted as a QoI, as documented below.
If an int is given, the quantity of interest is taken to be the slice output for the class/neuron/channel specified by the given integer, i.e., python quantities.InternalChannelQoI(qoi)
If a tuple or list of two integers is given, then the quantity of interest is taken to be the comparative quantity for the class given by the first integer against the class given by the second integer, i.e., ```python quantities.ComparativeQoI(*qoi)
If a callable is given, it is interpreted as a function\nrepresenting the QoI, i.e., ```python quantities.LambdaQoI(qoi)\n
If the string, 'max', is given, the quantity of interest is taken to be the output for the class with the maximum score, i.e., python quantities.MaxClassQoI()
'max' doi_cut For models which have non-differentiable pre-processing at the start of the model, specify the cut of the initial differentiable input form. For NLP models, for example, this could point to the embedding layer. If not provided, InputCut is assumed.
None doi distributions.DoI | str Distribution of interest over inputs. Expects a DoI object, or a related type that can be interpreted as a DoI, as documented below.
If the string, 'point', is given, the distribution is taken to be the single point passed to attributions, i.e., python distributions.PointDoi()
If the string, 'linear', is given, the distribution is taken to be the linear interpolation from the zero input to the point passed to attributions, i.e., python distributions.LinearDoi()
'point' multiply_activation bool, optional Whether to multiply the gradient result by its corresponding activation, thus converting from \"influence space\" to \"attribution space.\"
True Source code in
trulens_explain/trulens/nn/attribution.py def __init__(\n self,\n model: ModelWrapper,\n qoi_cut: CutLike = None, # see WARNING-LOAD-INIT\n qoi: QoiLike = 'max',\n doi_cut: CutLike = None, # see WARNING-LOAD-INIT\n doi: DoiLike = 'point',\n multiply_activation: bool = True,\n *args,\n **kwargs\n):\n\"\"\"\n Parameters:\n model :\n Model for which attributions are calculated.\n\n qoi_cut :\n The cut determining the layer from which the QoI is derived.\n Expects a `Cut` object, or a related type that can be\n interpreted as a `Cut`, as documented below.\n\n If an `int` is given, it represents the index of a layer in\n `model`. \n\n If a `str` is given, it represents the name of a layer in\n `model`. \n\n `None` is an alternative for `slices.OutputCut()`.\n\n qoi : quantities.QoI | int | tuple | str\n Quantity of interest to attribute. Expects a `QoI` object, or a\n related type that can be interpreted as a `QoI`, as documented\n below.\n\n If an `int` is given, the quantity of interest is taken to be\n the slice output for the class/neuron/channel specified by the\n given integer, i.e., ```python\n quantities.InternalChannelQoI(qoi) ```\n\n If a tuple or list of two integers is given, then the quantity\n of interest is taken to be the comparative quantity for the\n class given by the first integer against the class given by the\n second integer, i.e., ```python quantities.ComparativeQoI(*qoi)\n ```\n\n If a callable is given, it is interpreted as a function\n representing the QoI, i.e., ```python quantities.LambdaQoI(qoi)\n ```\n\n If the string, `'max'`, is given, the quantity of interest is\n taken to be the output for the class with the maximum score,\n i.e., ```python quantities.MaxClassQoI() ```\n\n doi_cut :\n For models which have non-differentiable pre-processing at the\n start of the model, specify the cut of the initial\n differentiable input form. For NLP models, for example, this\n could point to the embedding layer. If not provided, InputCut is\n assumed.\n\n doi : distributions.DoI | str\n Distribution of interest over inputs. Expects a `DoI` object, or\n a related type that can be interpreted as a `DoI`, as documented\n below.\n\n If the string, `'point'`, is given, the distribution is taken to\n be the single point passed to `attributions`, i.e., ```python\n distributions.PointDoi() ```\n\n If the string, `'linear'`, is given, the distribution is taken\n to be the linear interpolation from the zero input to the point\n passed to `attributions`, i.e., ```python\n distributions.LinearDoi() ```\n\n multiply_activation : bool, optional\n Whether to multiply the gradient result by its corresponding\n activation, thus converting from \"*influence space*\" to\n \"*attribution space*.\"\n \"\"\"\n if doi_cut is None:\n # WARNING-LOAD-INIT: Do not put this as a default arg in the def\n # line. That would cause an instantiation of InputCut when this\n # class is loaded and before it is used. Because get_backend gets\n # called in Cut.__init__, it may fail if this class is loaded before\n # trulens.nn.models.get_model_wrapper is called on some model.\n doi_cut = InputCut()\n\n super().__init__(\n model, (doi_cut, qoi_cut),\n qoi,\n doi,\n multiply_activation=multiply_activation,\n *args,\n **kwargs\n )\n
"},{"location":"trulens_explain/api/attribution/#trulens_explain.trulens.nn.attribution.IntegratedGradients","title":"
IntegratedGradients","text":"
Bases: InputAttribution
Implementation for the Integrated Gradients method from the following paper:
Axiomatic Attribution for Deep Networks
This should be cited using:
@INPROCEEDINGS{\nsundararajan17axiomatic,\nauthor={Mukund Sundararajan and Ankur Taly, and Qiqi Yan},\ntitle={Axiomatic Attribution for Deep Networks},\nbooktitle={International Conference on Machine Learning (ICML)},\nyear={2017},\n}\n
This is essentially an alias for
InternalInfluence(\n model,\n (trulens.nn.slices.InputCut(), trulens.nn.slices.OutputCut()),\n 'max',\n trulens.nn.distributions.LinearDoi(baseline, resolution),\n multiply_activation=True)\n
Source code in
trulens_explain/trulens/nn/attribution.py class IntegratedGradients(InputAttribution):\n\"\"\"\n Implementation for the Integrated Gradients method from the following paper:\n\n [Axiomatic Attribution for Deep Networks](\n https://arxiv.org/pdf/1703.01365)\n\n This should be cited using:\n\n ```bibtex\n @INPROCEEDINGS{\n sundararajan17axiomatic,\n author={Mukund Sundararajan and Ankur Taly, and Qiqi Yan},\n title={Axiomatic Attribution for Deep Networks},\n booktitle={International Conference on Machine Learning (ICML)},\n year={2017},\n }\n ```\n\n This is essentially an alias for\n\n ```python\n InternalInfluence(\n model,\n (trulens.nn.slices.InputCut(), trulens.nn.slices.OutputCut()),\n 'max',\n trulens.nn.distributions.LinearDoi(baseline, resolution),\n multiply_activation=True)\n ```\n \"\"\"\n\n def __init__(\n self,\n model: ModelWrapper,\n baseline=None,\n resolution: int = 50,\n doi_cut=None, # see WARNING-LOAD-INIT\n qoi='max',\n qoi_cut=None, # see WARNING-LOAD-INIT\n *args,\n **kwargs\n ):\n\"\"\"\n Parameters:\n model:\n Model for which attributions are calculated.\n\n baseline:\n The baseline to interpolate from. Must be same shape as the \n input. If `None` is given, the zero vector in the appropriate \n shape will be used.\n\n resolution:\n Number of points to use in the approximation. A higher \n resolution is more computationally expensive, but gives a better\n approximation of the mathematical formula this attribution \n method represents.\n \"\"\"\n\n if doi_cut is None:\n doi_cut = InputCut()\n\n if qoi_cut is None:\n qoi_cut = OutputCut()\n\n super().__init__(\n model=model,\n qoi_cut=qoi_cut,\n qoi=qoi,\n doi_cut=doi_cut,\n doi=LinearDoi(baseline, resolution, cut=doi_cut),\n multiply_activation=True,\n *args,\n **kwargs\n )\n
"},{"location":"trulens_explain/api/attribution/#trulens_explain.trulens.nn.attribution.IntegratedGradients.__init__","title":"
__init__(model, baseline=None, resolution=50, doi_cut=None, qoi='max', qoi_cut=None, *args, **kwargs)","text":"
Parameters:
Name Type Description Default
model ModelWrapper Model for which attributions are calculated.
required
baseline The baseline to interpolate from. Must be same shape as the input. If None is given, the zero vector in the appropriate shape will be used.
None resolution int Number of points to use in the approximation. A higher resolution is more computationally expensive, but gives a better approximation of the mathematical formula this attribution method represents.
50 Source code in
trulens_explain/trulens/nn/attribution.py def __init__(\n self,\n model: ModelWrapper,\n baseline=None,\n resolution: int = 50,\n doi_cut=None, # see WARNING-LOAD-INIT\n qoi='max',\n qoi_cut=None, # see WARNING-LOAD-INIT\n *args,\n **kwargs\n):\n\"\"\"\n Parameters:\n model:\n Model for which attributions are calculated.\n\n baseline:\n The baseline to interpolate from. Must be same shape as the \n input. If `None` is given, the zero vector in the appropriate \n shape will be used.\n\n resolution:\n Number of points to use in the approximation. A higher \n resolution is more computationally expensive, but gives a better\n approximation of the mathematical formula this attribution \n method represents.\n \"\"\"\n\n if doi_cut is None:\n doi_cut = InputCut()\n\n if qoi_cut is None:\n qoi_cut = OutputCut()\n\n super().__init__(\n model=model,\n qoi_cut=qoi_cut,\n qoi=qoi,\n doi_cut=doi_cut,\n doi=LinearDoi(baseline, resolution, cut=doi_cut),\n multiply_activation=True,\n *args,\n **kwargs\n )\n
"},{"location":"trulens_explain/api/attribution/#trulens_explain.trulens.nn.attribution.InternalInfluence","title":"
InternalInfluence","text":"
Bases: AttributionMethod
Internal attributions parameterized by a slice, quantity of interest, and distribution of interest.
The slice specifies the layers at which the internals of the model are to be exposed; it is represented by two cuts, which specify the layer the attributions are assigned to and the layer from which the quantity of interest is derived. The Quantity of Interest (QoI) is a function of the output specified by the slice that determines the network output behavior that the attributions are to describe. The Distribution of Interest (DoI) specifies the records over which the attributions are aggregated.
More information can be found in the following paper:
Influence-Directed Explanations for Deep Convolutional Networks
This should be cited using:
@INPROCEEDINGS{\nleino18influence,\nauthor={\n Klas Leino and\n Shayak Sen and\n Anupam Datta and\n Matt Fredrikson and\n Linyi Li},\ntitle={\n Influence-Directed Explanations\n for Deep Convolutional Networks},\nbooktitle={IEEE International Test Conference (ITC)},\nyear={2018},\n}\n
Source code in
trulens_explain/trulens/nn/attribution.py class InternalInfluence(AttributionMethod):\n\"\"\"Internal attributions parameterized by a slice, quantity of interest, and\n distribution of interest.\n\n The *slice* specifies the layers at which the internals of the model are to\n be exposed; it is represented by two *cuts*, which specify the layer the\n attributions are assigned to and the layer from which the quantity of\n interest is derived. The *Quantity of Interest* (QoI) is a function of the\n output specified by the slice that determines the network output behavior\n that the attributions are to describe. The *Distribution of Interest* (DoI)\n specifies the records over which the attributions are aggregated.\n\n More information can be found in the following paper:\n\n [Influence-Directed Explanations for Deep Convolutional Networks](\n https://arxiv.org/pdf/1802.03788.pdf)\n\n This should be cited using:\n\n ```bibtex\n @INPROCEEDINGS{\n leino18influence,\n author={\n Klas Leino and\n Shayak Sen and\n Anupam Datta and\n Matt Fredrikson and\n Linyi Li},\n title={\n Influence-Directed Explanations\n for Deep Convolutional Networks},\n booktitle={IEEE International Test Conference (ITC)},\n year={2018},\n }\n ```\n \"\"\"\n\n def __init__(\n self,\n model: ModelWrapper,\n cuts: SliceLike,\n qoi: QoiLike,\n doi: DoiLike,\n multiply_activation: bool = True,\n return_grads: bool = False,\n return_doi: bool = False,\n *args,\n **kwargs\n ):\n\"\"\"\n Parameters:\n model:\n Model for which attributions are calculated.\n\n cuts: \n The slice to use when computing the attributions. The slice \n keeps track of the layer whose output attributions are \n calculated and the layer for which the quantity of interest is \n computed. Expects a `Slice` object, or a related type that can\n be interpreted as a `Slice`, as documented below.\n\n If a single `Cut` object is given, it is assumed to be the cut \n representing the layer for which attributions are calculated \n (i.e., `from_cut` in `Slice`) and the layer for the quantity of \n interest (i.e., `to_cut` in `slices.Slice`) is taken to be the \n output of the network. If a tuple or list of two `Cut`s is \n given, they are assumed to be `from_cut` and `to_cut`, \n respectively.\n\n A cut (or the cuts within the tuple) can also be represented as \n an `int`, `str`, or `None`. If an `int` is given, it represents \n the index of a layer in `model`. If a `str` is given, it \n represents the name of a layer in `model`. `None` is an \n alternative for `slices.InputCut`.\n\n qoi:\n Quantity of interest to attribute. Expects a `QoI` object, or a\n related type that can be interpreted as a `QoI`, as documented\n below.\n\n If an `int` is given, the quantity of interest is taken to be \n the slice output for the class/neuron/channel specified by the \n given integer, i.e., \n ```python\n quantities.InternalChannelQoI(qoi)\n ```\n\n If a tuple or list of two integers is given, then the quantity \n of interest is taken to be the comparative quantity for the \n class given by the first integer against the class given by the \n second integer, i.e., \n ```python\n quantities.ComparativeQoI(*qoi)\n ```\n\n If a callable is given, it is interpreted as a function\n representing the QoI, i.e.,\n ```python\n quantities.LambdaQoI(qoi)\n ```\n\n If the string, `'max'`, is given, the quantity of interest is \n taken to be the output for the class with the maximum score, \n i.e., \n ```python\n quantities.MaxClassQoI()\n ```\n\n doi:\n Distribution of interest over inputs. Expects a `DoI` object, or\n a related type that can be interpreted as a `DoI`, as documented\n below.\n\n If the string, `'point'`, is given, the distribution is taken to\n be the single point passed to `attributions`, i.e., \n ```python\n distributions.PointDoi()\n ```\n\n If the string, `'linear'`, is given, the distribution is taken \n to be the linear interpolation from the zero input to the point \n passed to `attributions`, i.e., \n ```python\n distributions.LinearDoi()\n ```\n\n multiply_activation:\n Whether to multiply the gradient result by its corresponding\n activation, thus converting from \"*influence space*\" to \n \"*attribution space*.\"\n \"\"\"\n super().__init__(model, *args, **kwargs)\n\n self.slice = InternalInfluence.__get_slice(cuts)\n self.qoi = InternalInfluence.__get_qoi(qoi)\n self.doi = InternalInfluence.__get_doi(doi, cut=self.slice.from_cut)\n self._do_multiply = multiply_activation\n self._return_grads = return_grads\n self._return_doi = return_doi\n\n def _attributions(self, model_inputs: ModelInputs) -> AttributionResult:\n # NOTE: not symbolic\n\n B = get_backend()\n results = AttributionResult()\n\n # Create a message for out-of-memory errors regarding float and batch size.\n first_batchable = model_inputs.first_batchable(B)\n if first_batchable is None:\n batch_size = 1\n else:\n batch_size = first_batchable.shape[0]\n\n param_msgs = [\n f\"float size = {B.floatX_size} ({B.floatX}); consider changing to a smaller type.\",\n f\"batch size = {batch_size}; consider reducing the size of the batch you send to the attributions method.\"\n ]\n\n doi_cut = self.doi.cut() if self.doi.cut() else InputCut()\n\n with memory_suggestions(*param_msgs): # Handles out-of-memory messages.\n doi_val: List[B.Tensor] = self.model._fprop(\n model_inputs=model_inputs,\n to_cut=doi_cut,\n doi_cut=InputCut(),\n attribution_cut=None, # InputCut(),\n intervention=model_inputs\n )[0]\n\n doi_val = nested_map(doi_val, B.as_array)\n\n D = self.doi._wrap_public_call(doi_val, model_inputs=model_inputs)\n\n if self._return_doi:\n results.interventions = D # : Inputs[Uniform[TensorLike]]\n\n D_tensors = D[0]\n n_doi = len(D_tensors)\n if isinstance(D_tensors, MAP_CONTAINER_TYPE):\n for k in D_tensors.keys():\n if isinstance(D_tensors[k], DATA_CONTAINER_TYPE):\n n_doi = len(D_tensors[k])\n D = self.__concatenate_doi(D)\n rebatch_size = self.rebatch_size\n if rebatch_size is None:\n rebatch_size = len(D[0])\n\n intervention = TensorArgs(args=D)\n model_inputs_expanded = tile(what=model_inputs, onto=intervention)\n # Create a message for out-of-memory errors regarding doi_size.\n # TODO: Generalize this message to doi other than LinearDoI:\n doi_size_msg = f\"distribution of interest size = {n_doi}; consider reducing intervention resolution.\"\n\n combined_batch_size = n_doi * batch_size\n combined_batch_msg = f\"combined batch size = {combined_batch_size}; consider reducing batch size, intervention size\"\n\n rebatch_size_msg = f\"rebatch_size = {rebatch_size}; consider reducing this AttributionMethod constructor parameter (default is same as combined batch size).\"\n\n # Calculate the gradient of each of the points in the DoI.\n with memory_suggestions(\n param_msgs +\n [doi_size_msg, combined_batch_msg, rebatch_size_msg]\n ): # Handles out-of-memory messages.\n qoi_grads_expanded: List[Outputs[Inputs[TensorLike]]] = []\n\n for inputs_batch, intervention_batch in rebatch(\n model_inputs_expanded, intervention,\n batch_size=rebatch_size):\n\n qoi_grads_expanded_batch: Outputs[\n Inputs[TensorLike]] = self.model._qoi_bprop(\n qoi=self.qoi,\n model_inputs=inputs_batch,\n attribution_cut=self.slice.from_cut,\n to_cut=self.slice.to_cut,\n intervention=intervention_batch,\n doi_cut=doi_cut\n )\n\n # important to cast to numpy inside loop:\n qoi_grads_expanded.append(\n nested_map(qoi_grads_expanded_batch, B.as_array)\n )\n\n num_outputs = len(qoi_grads_expanded[0])\n num_inputs = len(qoi_grads_expanded[0][0])\n transpose = [\n [[] for _ in range(num_inputs)] for _ in range(num_outputs)\n ]\n for o in range(num_outputs):\n for i in range(num_inputs):\n for qoi_grads_batch in qoi_grads_expanded:\n transpose[o][i].append(qoi_grads_batch[o][i])\n\n def container_concat(x):\n\"\"\"Applies np concatenate on a container. If it is a map type, it will apply it on each key.\n\n Args:\n x (map or data container): A container of tensors\n\n Returns:\n concatenated tensors of the container.\n \"\"\"\n if isinstance(x[0], MAP_CONTAINER_TYPE):\n ret_map = {}\n for k in x[0].keys():\n ret_map[k] = np.concatenate([_dict[k] for _dict in x])\n return ret_map\n else:\n return np.concatenate(x)\n\n qoi_grads_expanded: Outputs[Inputs[np.ndarray]] = nested_map(\n transpose, container_concat, nest=2\n )\n qoi_grads_expanded: Outputs[Inputs[np.ndarray]] = nested_map(\n qoi_grads_expanded,\n lambda grad: np.reshape(grad, (n_doi, -1) + grad.shape[1:]),\n nest=2\n )\n if self._return_grads:\n results.gradients = qoi_grads_expanded # : Outputs[Inputs[Uniform[TensorLike]]]\n\n # TODO: Does this need to be done in numpy?\n attrs: Outputs[Inputs[TensorLike]] = nested_map(\n qoi_grads_expanded, lambda grad: np.mean(grad, axis=0), nest=2\n )\n\n # Multiply by the activation multiplier if specified.\n if self._do_multiply:\n with memory_suggestions(param_msgs):\n z_val = self.model._fprop(\n model_inputs=model_inputs,\n doi_cut=InputCut(),\n attribution_cut=None,\n to_cut=self.slice.from_cut,\n intervention=model_inputs # intentional\n )[0]\n\n mults: Inputs[TensorLike\n ] = self.doi._wrap_public_get_activation_multiplier(\n z_val, model_inputs=model_inputs\n )\n mults: Inputs[np.ndarray] = nested_cast(\n backend=B, args=mults, astype=np.ndarray\n )\n mult_attrs = []\n for attr in attrs: # Outputs\n\n zipped = nested_zip(attr, mults)\n\n def zip_mult(zipped_attr_mults):\n attr = zipped_attr_mults[0]\n mults = zipped_attr_mults[1]\n return attr * mults\n\n attr = nested_map(\n zipped, zip_mult, check_accessor=lambda x: x[0]\n )\n mult_attrs.append(attr)\n attrs = mult_attrs\n results.attributions = attrs # : Outputs[Inputs[TensorLike]]\n\n return results\n\n @staticmethod\n def __get_qoi(qoi_arg):\n\"\"\"\n Helper function to get a `QoI` object from more user-friendly primitive \n arguments.\n \"\"\"\n # TODO(klas): we could potentially do some basic error catching here,\n # for example, making sure the index for a given channel is in range.\n\n if isinstance(qoi_arg, QoI):\n # We were already given a QoI, so return it.\n return qoi_arg\n\n elif callable(qoi_arg):\n # If we were given a callable, treat that function as a QoI.\n return LambdaQoI(qoi_arg)\n\n elif isinstance(qoi_arg, int):\n # If we receive an int, we take it to be the class/channel index\n # (whether it's a class or channel depends on the layer the quantity\n # is for, but `InternalChannelQoI` generalizes to both).\n return InternalChannelQoI(qoi_arg)\n\n elif isinstance(qoi_arg, DATA_CONTAINER_TYPE):\n # If we receive a DATA_CONTAINER_TYPE, we take it to be two classes\n # for which we are performing a comparative quantity of interest.\n if len(qoi_arg) == 2:\n return ComparativeQoI(*qoi_arg)\n\n else:\n raise ValueError(\n 'Tuple or list argument for `qoi` must have length 2'\n )\n\n elif isinstance(qoi_arg, str):\n # We can specify `MaxClassQoI` via the string 'max'.\n if qoi_arg == 'max':\n return MaxClassQoI()\n\n else:\n raise ValueError(\n 'String argument for `qoi` must be one of the following:\\n'\n ' - \"max\"'\n )\n\n else:\n raise ValueError('Unrecognized argument type for `qoi`')\n\n @staticmethod\n def __get_doi(doi_arg, cut=None):\n\"\"\"\n Helper function to get a `DoI` object from more user-friendly primitive \n arguments.\n \"\"\"\n if isinstance(doi_arg, DoI):\n # We were already given a DoI, so return it.\n return doi_arg\n\n elif isinstance(doi_arg, str):\n # We can specify `PointDoi` via the string 'point', or `LinearDoi`\n # via the string 'linear'.\n if doi_arg == 'point':\n return PointDoi(cut=cut)\n\n elif doi_arg == 'linear':\n return LinearDoi(cut=cut)\n\n else:\n raise ValueError(\n 'String argument for `doi` must be one of the following:\\n'\n ' - \"point\"\\n'\n ' - \"linear\"'\n )\n\n else:\n raise ValueError('Unrecognized argument type for `doi`')\n\n @staticmethod\n def __get_slice(slice_arg):\n\"\"\"\n Helper function to get a `Slice` object from more user-friendly\n primitive arguments.\n \"\"\"\n if isinstance(slice_arg, Slice):\n # We are already given a Slice, so return it.\n return slice_arg\n\n elif (isinstance(slice_arg, Cut) or isinstance(slice_arg, int) or\n isinstance(slice_arg, str) or slice_arg is None or\n slice_arg == 0):\n\n # If we receive a Cut, we take it to be the Cut of the start layer.\n return Slice(InternalInfluence.__get_cut(slice_arg), OutputCut())\n\n elif isinstance(slice_arg, DATA_CONTAINER_TYPE):\n # If we receive a DATA_CONTAINER_TYPE, we take it to be the start\n # and end layer of the slice.\n if len(slice_arg) == 2:\n if slice_arg[1] is None:\n return Slice(\n InternalInfluence.__get_cut(slice_arg[0]), OutputCut()\n )\n else:\n return Slice(\n InternalInfluence.__get_cut(slice_arg[0]),\n InternalInfluence.__get_cut(slice_arg[1])\n )\n\n else:\n raise ValueError(\n 'Tuple or list argument for `cuts` must have length 2'\n )\n\n else:\n raise ValueError('Unrecognized argument type for `cuts`')\n\n @staticmethod\n def __get_cut(cut_arg):\n\"\"\"\n Helper function to get a `Cut` object from more user-friendly primitive\n arguments.\n \"\"\"\n if isinstance(cut_arg, Cut):\n # We are already given a Cut, so return it.\n return cut_arg\n\n elif cut_arg is None or cut_arg == 0:\n # If we receive None or zero, we take it to be the input cut.\n return InputCut()\n\n # TODO(klas): may want a bit more validation here.\n elif isinstance(cut_arg, int) or isinstance(cut_arg, str):\n return Cut(cut_arg)\n\n else:\n raise ValueError('Unrecognized argument type for cut')\n\n @staticmethod\n def __concatenate_doi(D: Inputs[Uniform[TensorLike]]) -> Inputs[TensorLike]:\n # Returns one TensorLike for each model input.\n if len(D[0]) == 0:\n raise ValueError(\n 'Got empty distribution of interest. `DoI` must return at '\n 'least one point.'\n )\n # TODO: should this always be done in numpy or can we do it in backend?\n D = nested_cast(backend=get_backend(), args=D, astype=np.ndarray)\n ret = nested_map(D, np.concatenate, nest=1)\n return ret\n
"},{"location":"trulens_explain/api/attribution/#trulens_explain.trulens.nn.attribution.InternalInfluence.__init__","title":"
__init__(model, cuts, qoi, doi, multiply_activation=True, return_grads=False, return_doi=False, *args, **kwargs)","text":"
Parameters:
Name Type Description Default
model ModelWrapper Model for which attributions are calculated.
required
cuts SliceLike The slice to use when computing the attributions. The slice keeps track of the layer whose output attributions are calculated and the layer for which the quantity of interest is computed. Expects a Slice object, or a related type that can be interpreted as a Slice, as documented below.
If a single Cut object is given, it is assumed to be the cut representing the layer for which attributions are calculated (i.e., from_cut in Slice) and the layer for the quantity of interest (i.e., to_cut in slices.Slice) is taken to be the output of the network. If a tuple or list of two Cuts is given, they are assumed to be from_cut and to_cut, respectively.
A cut (or the cuts within the tuple) can also be represented as an int, str, or None. If an int is given, it represents the index of a layer in model. If a str is given, it represents the name of a layer in model. None is an alternative for slices.InputCut.
required
qoi QoiLike Quantity of interest to attribute. Expects a QoI object, or a related type that can be interpreted as a QoI, as documented below.
If an int is given, the quantity of interest is taken to be the slice output for the class/neuron/channel specified by the given integer, i.e.,
quantities.InternalChannelQoI(qoi)\n
If a tuple or list of two integers is given, then the quantity of interest is taken to be the comparative quantity for the class given by the first integer against the class given by the second integer, i.e.,
quantities.ComparativeQoI(*qoi)\n
If a callable is given, it is interpreted as a function representing the QoI, i.e.,
quantities.LambdaQoI(qoi)\n
If the string, 'max', is given, the quantity of interest is taken to be the output for the class with the maximum score, i.e.,
quantities.MaxClassQoI()\n
required
doi DoiLike Distribution of interest over inputs. Expects a DoI object, or a related type that can be interpreted as a DoI, as documented below.
If the string, 'point', is given, the distribution is taken to be the single point passed to attributions, i.e.,
distributions.PointDoi()\n
If the string, 'linear', is given, the distribution is taken to be the linear interpolation from the zero input to the point passed to attributions, i.e.,
distributions.LinearDoi()\n
required
multiply_activation bool Whether to multiply the gradient result by its corresponding activation, thus converting from \"influence space\" to \"attribution space.\"
True Source code in
trulens_explain/trulens/nn/attribution.py def __init__(\n self,\n model: ModelWrapper,\n cuts: SliceLike,\n qoi: QoiLike,\n doi: DoiLike,\n multiply_activation: bool = True,\n return_grads: bool = False,\n return_doi: bool = False,\n *args,\n **kwargs\n):\n\"\"\"\n Parameters:\n model:\n Model for which attributions are calculated.\n\n cuts: \n The slice to use when computing the attributions. The slice \n keeps track of the layer whose output attributions are \n calculated and the layer for which the quantity of interest is \n computed. Expects a `Slice` object, or a related type that can\n be interpreted as a `Slice`, as documented below.\n\n If a single `Cut` object is given, it is assumed to be the cut \n representing the layer for which attributions are calculated \n (i.e., `from_cut` in `Slice`) and the layer for the quantity of \n interest (i.e., `to_cut` in `slices.Slice`) is taken to be the \n output of the network. If a tuple or list of two `Cut`s is \n given, they are assumed to be `from_cut` and `to_cut`, \n respectively.\n\n A cut (or the cuts within the tuple) can also be represented as \n an `int`, `str`, or `None`. If an `int` is given, it represents \n the index of a layer in `model`. If a `str` is given, it \n represents the name of a layer in `model`. `None` is an \n alternative for `slices.InputCut`.\n\n qoi:\n Quantity of interest to attribute. Expects a `QoI` object, or a\n related type that can be interpreted as a `QoI`, as documented\n below.\n\n If an `int` is given, the quantity of interest is taken to be \n the slice output for the class/neuron/channel specified by the \n given integer, i.e., \n ```python\n quantities.InternalChannelQoI(qoi)\n ```\n\n If a tuple or list of two integers is given, then the quantity \n of interest is taken to be the comparative quantity for the \n class given by the first integer against the class given by the \n second integer, i.e., \n ```python\n quantities.ComparativeQoI(*qoi)\n ```\n\n If a callable is given, it is interpreted as a function\n representing the QoI, i.e.,\n ```python\n quantities.LambdaQoI(qoi)\n ```\n\n If the string, `'max'`, is given, the quantity of interest is \n taken to be the output for the class with the maximum score, \n i.e., \n ```python\n quantities.MaxClassQoI()\n ```\n\n doi:\n Distribution of interest over inputs. Expects a `DoI` object, or\n a related type that can be interpreted as a `DoI`, as documented\n below.\n\n If the string, `'point'`, is given, the distribution is taken to\n be the single point passed to `attributions`, i.e., \n ```python\n distributions.PointDoi()\n ```\n\n If the string, `'linear'`, is given, the distribution is taken \n to be the linear interpolation from the zero input to the point \n passed to `attributions`, i.e., \n ```python\n distributions.LinearDoi()\n ```\n\n multiply_activation:\n Whether to multiply the gradient result by its corresponding\n activation, thus converting from \"*influence space*\" to \n \"*attribution space*.\"\n \"\"\"\n super().__init__(model, *args, **kwargs)\n\n self.slice = InternalInfluence.__get_slice(cuts)\n self.qoi = InternalInfluence.__get_qoi(qoi)\n self.doi = InternalInfluence.__get_doi(doi, cut=self.slice.from_cut)\n self._do_multiply = multiply_activation\n self._return_grads = return_grads\n self._return_doi = return_doi\n
"},{"location":"trulens_explain/api/distributions/","title":"Distributions of Interest","text":"
The distribution of interest lets us specify the set of samples over which we want our explanations to be faithful. In some cases, we may want to explain the model\u2019s behavior on a particular record, whereas other times we may be interested in a more general behavior over a distribution of samples.
"},{"location":"trulens_explain/api/distributions/#trulens_explain.trulens.nn.distributions.DoI","title":"
DoI","text":"
Bases: AbstractBaseClass
Interface for distributions of interest. The Distribution of Interest (DoI) specifies the samples over which an attribution method is aggregated.
Source code in
trulens_explain/trulens/nn/distributions.py class DoI(AbstractBaseClass):\n\"\"\"\n Interface for distributions of interest. The *Distribution of Interest* \n (DoI) specifies the samples over which an attribution method is \n aggregated.\n \"\"\"\n\n def __init__(self, cut: Cut = None):\n\"\"\"\"Initialize DoI\n\n Parameters:\n cut (Cut, optional): \n The Cut in which the DoI will be applied. If `None`, the DoI will be\n applied to the input. otherwise, the distribution should be applied\n to the latent space defined by the cut. \n \"\"\"\n self._cut = cut\n\n def __str__(self):\n return render_object(self, ['_cut'])\n\n def _wrap_public_call(\n self, z: Inputs[TensorLike], *, model_inputs: ModelInputs\n ) -> Inputs[Uniform[TensorLike]]:\n\"\"\"Same as __call__ but input and output types are more specific and\n less permissive. Formats the inputs for special cases that might be more\n convenient for the user's __call__ implementation and formats its return\n back to the consistent type.\"\"\"\n\n z: Inputs[TensorLike] = om_of_many(z)\n\n if accepts_model_inputs(self.__call__):\n ret = self.__call__(z, model_inputs=model_inputs)\n else:\n ret = self.__call__(z)\n # Wrap the public doi generator with appropriate type aliases.\n if isinstance(ret, DATA_CONTAINER_TYPE):\n if isinstance(ret[0], DATA_CONTAINER_TYPE):\n ret = Inputs(Uniform(x) for x in ret)\n else:\n ret = Uniform(ret)\n\n ret: Inputs[Uniform[TensorLike]] = many_of_om(\n ret, innertype=Uniform\n )\n else:\n ret: ArgsLike = [ret]\n return ret\n\n @abstractmethod\n def __call__(\n self,\n z: OM[Inputs, TensorLike],\n *,\n model_inputs: Optional[ModelInputs] = None\n ) -> OM[Inputs, Uniform[TensorLike]]:\n\"\"\"\n Computes the distribution of interest from an initial point. If z:\n TensorLike is given, we assume there is only 1 input to the DoI layer. If\n z: List[TensorLike] is given, it provides all of the inputs to the DoI\n layer. \n\n Either way, we always return List[List[TensorLike]] (alias\n Inputs[Uniform[TensorLike]]) with outer list spanning layer inputs, and\n inner list spanning a distribution's instance.\n\n Parameters:\n z:\n Input point from which the distribution is derived. If\n list/tuple, the point is defined by multiple tensors.\n model_inputs:\n Optional wrapped model input arguments that produce value z at\n cut.\n\n Returns:\n List of points which are all assigned equal probability mass in the\n distribution of interest, i.e., the distribution of interest is a\n discrete, uniform distribution over the list of returned points. If\n z is multi-input, returns a distribution for each input.\n \"\"\"\n raise NotImplementedError\n\n # @property\n def cut(self) -> Cut:\n\"\"\"\n Returns:\n The Cut in which the DoI will be applied. If `None`, the DoI will be\n applied to the input. otherwise, the distribution should be applied\n to the latent space defined by the cut. \n \"\"\"\n return self._cut\n\n def _wrap_public_get_activation_multiplier(\n self, activation: Inputs[TensorLike], *, model_inputs: ModelInputs\n ) -> Inputs[TensorLike]:\n\"\"\"Same as get_activation_multiplier but without \"one-or-more\". \"\"\"\n\n activations: OM[Inputs, TensorLike] = om_of_many(activation)\n\n # get_activation_multiplier is public\n if accepts_model_inputs(self.get_activation_multiplier):\n ret: OM[Inputs, TensorLike] = self.get_activation_multiplier(\n activations, model_inputs=model_inputs\n )\n else:\n ret: OM[Inputs,\n TensorLike] = self.get_activation_multiplier(activations)\n\n ret: Inputs[TensorLike] = many_of_om(ret)\n\n return ret\n\n def get_activation_multiplier(\n self,\n activation: OM[Inputs, TensorLike],\n *,\n model_inputs: Optional[ModelInputs] = None\n ) -> OM[Inputs, TensorLike]:\n\"\"\"\n Returns a term to multiply the gradient by to convert from \"*influence\n space*\" to \"*attribution space*\". Conceptually, \"influence space\"\n corresponds to the potential effect of a slight increase in each\n feature, while \"attribution space\" corresponds to an approximation of\n the net marginal contribution to the quantity of interest of each\n feature.\n\n Parameters:\n activation:\n The activation of the layer the DoI is applied to. DoI may be\n multi-input in which case activation will be a list.\n model_inputs:\n Optional wrapped model input arguments that produce activation\n at cut.\n\n Returns:\n An array with the same shape as ``activation`` that will be\n multiplied by the gradient to obtain the attribution. The default\n implementation of this method simply returns ``activation``. If\n activation is multi-input, returns one multiplier for each.\n \"\"\"\n return om_of_many(activation)\n\n def _assert_cut_contains_only_one_tensor(self, x):\n if isinstance(x, DATA_CONTAINER_TYPE) and len(x) == 1:\n x = x[0]\n if isinstance(x, MAP_CONTAINER_TYPE) and len(x) == 1:\n x = list(x.values())[0]\n\n if isinstance(x, list):\n raise DoiCutSupportError(\n '\\n\\n'\n 'Cut provided to distribution of interest was comprised of '\n 'multiple tensors, but `{}` is only defined for cuts comprised '\n 'of a single tensor (received a list of {} tensors).\\n'\n '\\n'\n 'Either (1) select a slice where the `to_cut` corresponds to a '\n 'single tensor, or (2) implement/use a `DoI` object that '\n 'supports lists of tensors, i.e., where the parameter, `z`, to '\n '`__call__` is expected/allowed to be a list of {} tensors.'.\n format(self.__class__.__name__, len(x), len(x))\n )\n\n elif not (isinstance(x, np.ndarray) or get_backend().is_tensor(x)):\n raise ValueError(\n '`{}` expected to receive an instance of `Tensor` or '\n '`np.ndarray`, but received an instance of {}'.format(\n self.__class__.__name__, type(x)\n )\n )\n
"},{"location":"trulens_explain/api/distributions/#trulens_explain.trulens.nn.distributions.DoI.__call__","title":"
__call__(z, *, model_inputs=None) abstractmethod","text":"
Computes the distribution of interest from an initial point. If z: TensorLike is given, we assume there is only 1 input to the DoI layer. If z: List[TensorLike] is given, it provides all of the inputs to the DoI layer.
Either way, we always return List[List[TensorLike]] (alias Inputs[Uniform[TensorLike]]) with outer list spanning layer inputs, and inner list spanning a distribution's instance.
Parameters:
Name Type Description Default
z OM[Inputs, TensorLike] Input point from which the distribution is derived. If list/tuple, the point is defined by multiple tensors.
required
model_inputs Optional[ModelInputs] Optional wrapped model input arguments that produce value z at cut.
None Returns:
Type Description
OM[Inputs, Uniform[TensorLike]] List of points which are all assigned equal probability mass in the
OM[Inputs, Uniform[TensorLike]] distribution of interest, i.e., the distribution of interest is a
OM[Inputs, Uniform[TensorLike]] discrete, uniform distribution over the list of returned points. If
OM[Inputs, Uniform[TensorLike]] z is multi-input, returns a distribution for each input.
Source code in
trulens_explain/trulens/nn/distributions.py @abstractmethod\ndef __call__(\n self,\n z: OM[Inputs, TensorLike],\n *,\n model_inputs: Optional[ModelInputs] = None\n) -> OM[Inputs, Uniform[TensorLike]]:\n\"\"\"\n Computes the distribution of interest from an initial point. If z:\n TensorLike is given, we assume there is only 1 input to the DoI layer. If\n z: List[TensorLike] is given, it provides all of the inputs to the DoI\n layer. \n\n Either way, we always return List[List[TensorLike]] (alias\n Inputs[Uniform[TensorLike]]) with outer list spanning layer inputs, and\n inner list spanning a distribution's instance.\n\n Parameters:\n z:\n Input point from which the distribution is derived. If\n list/tuple, the point is defined by multiple tensors.\n model_inputs:\n Optional wrapped model input arguments that produce value z at\n cut.\n\n Returns:\n List of points which are all assigned equal probability mass in the\n distribution of interest, i.e., the distribution of interest is a\n discrete, uniform distribution over the list of returned points. If\n z is multi-input, returns a distribution for each input.\n \"\"\"\n raise NotImplementedError\n
"},{"location":"trulens_explain/api/distributions/#trulens_explain.trulens.nn.distributions.DoI.__init__","title":"
__init__(cut=None)","text":"
\"Initialize DoI
Parameters:
Name Type Description Default
cut Cut The Cut in which the DoI will be applied. If None, the DoI will be applied to the input. otherwise, the distribution should be applied to the latent space defined by the cut.
None Source code in
trulens_explain/trulens/nn/distributions.py def __init__(self, cut: Cut = None):\n\"\"\"\"Initialize DoI\n\n Parameters:\n cut (Cut, optional): \n The Cut in which the DoI will be applied. If `None`, the DoI will be\n applied to the input. otherwise, the distribution should be applied\n to the latent space defined by the cut. \n \"\"\"\n self._cut = cut\n
"},{"location":"trulens_explain/api/distributions/#trulens_explain.trulens.nn.distributions.DoI.cut","title":"
cut()","text":"
Returns:
Type Description
Cut The Cut in which the DoI will be applied. If None, the DoI will be
Cut applied to the input. otherwise, the distribution should be applied
Cut to the latent space defined by the cut.
Source code in
trulens_explain/trulens/nn/distributions.py def cut(self) -> Cut:\n\"\"\"\n Returns:\n The Cut in which the DoI will be applied. If `None`, the DoI will be\n applied to the input. otherwise, the distribution should be applied\n to the latent space defined by the cut. \n \"\"\"\n return self._cut\n
"},{"location":"trulens_explain/api/distributions/#trulens_explain.trulens.nn.distributions.DoI.get_activation_multiplier","title":"
get_activation_multiplier(activation, *, model_inputs=None)","text":"
Returns a term to multiply the gradient by to convert from \"influence space\" to \"attribution space\". Conceptually, \"influence space\" corresponds to the potential effect of a slight increase in each feature, while \"attribution space\" corresponds to an approximation of the net marginal contribution to the quantity of interest of each feature.
Parameters:
Name Type Description Default
activation OM[Inputs, TensorLike] The activation of the layer the DoI is applied to. DoI may be multi-input in which case activation will be a list.
required
model_inputs Optional[ModelInputs] Optional wrapped model input arguments that produce activation at cut.
None Returns:
Type Description
OM[Inputs, TensorLike] An array with the same shape as activation that will be
OM[Inputs, TensorLike] multiplied by the gradient to obtain the attribution. The default
OM[Inputs, TensorLike] implementation of this method simply returns activation. If
OM[Inputs, TensorLike] activation is multi-input, returns one multiplier for each.
Source code in
trulens_explain/trulens/nn/distributions.py def get_activation_multiplier(\n self,\n activation: OM[Inputs, TensorLike],\n *,\n model_inputs: Optional[ModelInputs] = None\n) -> OM[Inputs, TensorLike]:\n\"\"\"\n Returns a term to multiply the gradient by to convert from \"*influence\n space*\" to \"*attribution space*\". Conceptually, \"influence space\"\n corresponds to the potential effect of a slight increase in each\n feature, while \"attribution space\" corresponds to an approximation of\n the net marginal contribution to the quantity of interest of each\n feature.\n\n Parameters:\n activation:\n The activation of the layer the DoI is applied to. DoI may be\n multi-input in which case activation will be a list.\n model_inputs:\n Optional wrapped model input arguments that produce activation\n at cut.\n\n Returns:\n An array with the same shape as ``activation`` that will be\n multiplied by the gradient to obtain the attribution. The default\n implementation of this method simply returns ``activation``. If\n activation is multi-input, returns one multiplier for each.\n \"\"\"\n return om_of_many(activation)\n
"},{"location":"trulens_explain/api/distributions/#trulens_explain.trulens.nn.distributions.DoiCutSupportError","title":"
DoiCutSupportError","text":"
Bases: ValueError
Exception raised if the distribution of interest is called on a cut whose output is not supported by the distribution of interest.
Source code in
trulens_explain/trulens/nn/distributions.py class DoiCutSupportError(ValueError):\n\"\"\"\n Exception raised if the distribution of interest is called on a cut whose\n output is not supported by the distribution of interest.\n \"\"\"\n pass\n
"},{"location":"trulens_explain/api/distributions/#trulens_explain.trulens.nn.distributions.GaussianDoi","title":"
GaussianDoi","text":"
Bases: DoI
Distribution representing a Gaussian ball around the point. Used by Smooth Gradients.
Source code in
trulens_explain/trulens/nn/distributions.py class GaussianDoi(DoI):\n\"\"\"\n Distribution representing a Gaussian ball around the point. Used by Smooth\n Gradients.\n \"\"\"\n\n def __init__(self, var: float, resolution: int, cut: Cut = None):\n\"\"\"\n Parameters:\n var:\n The variance of the Gaussian noise to be added around the point.\n\n resolution:\n Number of samples returned by each call to this DoI.\n cut (Cut, optional): \n The Cut in which the DoI will be applied. If `None`, the DoI will be\n applied to the input. otherwise, the distribution should be applied\n to the latent space defined by the cut. \n \"\"\"\n super(GaussianDoi, self).__init__(cut)\n self._var = var\n self._resolution = resolution\n\n def __str__(self):\n return render_object(self, ['_cut', '_var', '_resolution'])\n\n def __call__(self, z: OM[Inputs,\n TensorLike]) -> OM[Inputs, Uniform[TensorLike]]:\n # Public interface.\n\n B = get_backend()\n self._assert_cut_contains_only_one_tensor(z)\n\n def gauss_of_input(z: TensorLike) -> Uniform[TensorLike]:\n # TODO: make a pytorch backend with the same interface to use in places like these.\n\n if B.is_tensor(z):\n # Tensor implementation.\n return [\n z + B.random_normal_like(z, var=self._var)\n for _ in range(self._resolution)\n ] # Uniform\n\n else:\n # Array implementation.\n return [\n z + np.random.normal(0., np.sqrt(self._var), z.shape)\n for _ in range(self._resolution)\n ] # Uniform\n\n z: Inputs[TensorLike] = many_of_om(z)\n\n return om_of_many(nested_map(z, gauss_of_input))\n
"},{"location":"trulens_explain/api/distributions/#trulens_explain.trulens.nn.distributions.GaussianDoi.__init__","title":"
__init__(var, resolution, cut=None)","text":"
Parameters:
Name Type Description Default
var float The variance of the Gaussian noise to be added around the point.
required
resolution int Number of samples returned by each call to this DoI.
required
cut Cut The Cut in which the DoI will be applied. If None, the DoI will be applied to the input. otherwise, the distribution should be applied to the latent space defined by the cut.
None Source code in
trulens_explain/trulens/nn/distributions.py def __init__(self, var: float, resolution: int, cut: Cut = None):\n\"\"\"\n Parameters:\n var:\n The variance of the Gaussian noise to be added around the point.\n\n resolution:\n Number of samples returned by each call to this DoI.\n cut (Cut, optional): \n The Cut in which the DoI will be applied. If `None`, the DoI will be\n applied to the input. otherwise, the distribution should be applied\n to the latent space defined by the cut. \n \"\"\"\n super(GaussianDoi, self).__init__(cut)\n self._var = var\n self._resolution = resolution\n
"},{"location":"trulens_explain/api/distributions/#trulens_explain.trulens.nn.distributions.LinearDoi","title":"
LinearDoi","text":"
Bases: DoI
Distribution representing the linear interpolation between a baseline and the given point. Used by Integrated Gradients.
Source code in
trulens_explain/trulens/nn/distributions.py class LinearDoi(DoI):\n\"\"\"\n Distribution representing the linear interpolation between a baseline and \n the given point. Used by Integrated Gradients.\n \"\"\"\n\n def __init__(\n self,\n baseline: BaselineLike = None,\n resolution: int = 10,\n *,\n cut: Cut = None,\n ):\n\"\"\"\n The DoI for point, `z`, will be a uniform distribution over the points\n on the line segment connecting `z` to `baseline`, approximated by a\n sample of `resolution` points equally spaced along this segment.\n\n Parameters:\n cut (Cut, optional, from DoI): \n The Cut in which the DoI will be applied. If `None`, the DoI\n will be applied to the input. otherwise, the distribution should\n be applied to the latent space defined by the cut. \n baseline (BaselineLike, optional):\n The baseline to interpolate from. Must be same shape as the\n space the distribution acts over, i.e., the shape of the points,\n `z`, eventually passed to `__call__`. If `cut` is `None`, this\n must be the same shape as the input, otherwise this must be the\n same shape as the latent space defined by the cut. If `None` is\n given, `baseline` will be the zero vector in the appropriate\n shape. If the baseline is callable, it is expected to return the\n `baseline`, given `z` and optional model arguments.\n resolution (int):\n Number of points returned by each call to this DoI. A higher\n resolution is more computationally expensive, but gives a better\n approximation of the DoI this object mathematically represents.\n \"\"\"\n super(LinearDoi, self).__init__(cut)\n self._baseline = baseline\n self._resolution = resolution\n\n @property\n def baseline(self) -> BaselineLike:\n return self._baseline\n\n @property\n def resolution(self) -> int:\n return self._resolution\n\n def __str__(self):\n return render_object(self, ['_cut', '_baseline', '_resolution'])\n\n def __call__(\n self,\n z: OM[Inputs, TensorLike],\n *,\n model_inputs: Optional[ModelInputs] = None\n ) -> OM[Inputs, Uniform[TensorLike]]:\n\n self._assert_cut_contains_only_one_tensor(z)\n\n z: Inputs[TensorLike] = many_of_om(z)\n\n baseline = self._compute_baseline(z, model_inputs=model_inputs)\n\n r = 1. if self._resolution == 1 else self._resolution - 1.\n zipped = nested_zip(z, baseline)\n\n def zipped_interpolate(zipped_z_baseline):\n\"\"\"interpolates zipped elements\n\n Args:\n zipped_z_baseline: A tuple expecting the first element to be the z_val, and second to be the baseline.\n\n Returns:\n a list of interpolations from z to baseline\n \"\"\"\n z_ = zipped_z_baseline[0]\n b_ = zipped_z_baseline[1]\n return [ # Uniform\n (1. - i / r) * z_ + i / r * b_\n for i in range(self._resolution)\n ]\n\n ret = om_of_many(\n nested_map(\n zipped, zipped_interpolate, check_accessor=lambda x: x[0]\n )\n )\n\n return ret\n\n def get_activation_multiplier(\n self,\n activation: OM[Inputs, TensorLike],\n *,\n model_inputs: Optional[ModelInputs] = None\n ) -> Inputs[TensorLike]:\n\"\"\"\n Returns a term to multiply the gradient by to convert from \"*influence \n space*\" to \"*attribution space*\". Conceptually, \"influence space\"\n corresponds to the potential effect of a slight increase in each \n feature, while \"attribution space\" corresponds to an approximation of\n the net marginal contribution to the quantity of interest of each \n feature.\n\n Parameters:\n activation:\n The activation of the layer the DoI is applied to.\n\n Returns:\n The activation adjusted by the baseline passed to the constructor.\n \"\"\"\n\n activation: Inputs[TensorLike] = many_of_om(activation)\n\n baseline: Inputs[TensorLike] = self._compute_baseline(\n activation, model_inputs=model_inputs\n )\n\n if baseline is None:\n return activation\n\n zipped = nested_zip(activation, baseline)\n\n def zipped_subtract(zipped_activation_baseline):\n\"\"\"subtracts zipped elements\n\n Args:\n zipped_activation_baseline: A tuple expecting the first element to be the activation, and second to be the baseline.\n\n Returns:\n a subtraction of activation and baseline\n \"\"\"\n activation = zipped_activation_baseline[0]\n baseline = zipped_activation_baseline[1]\n return activation - baseline\n\n ret = nested_map(zipped, zipped_subtract, check_accessor=lambda x: x[0])\n return ret\n\n def _compute_baseline(\n self,\n z: Inputs[TensorLike],\n *,\n model_inputs: Optional[ModelInputs] = None\n ) -> Inputs[TensorLike]:\n\n B = get_backend()\n\n _baseline: BaselineLike = self.baseline # user-provided\n\n if isinstance(_baseline, Callable):\n if accepts_model_inputs(_baseline):\n _baseline: OM[Inputs, TensorLike] = many_of_om(\n _baseline(om_of_many(z), model_inputs=model_inputs)\n )\n else:\n _baseline: OM[Inputs, TensorLike] = many_of_om(\n _baseline(om_of_many(z))\n )\n\n else:\n _baseline: OM[Inputs, TensorLike]\n\n if _baseline is None:\n _baseline: Inputs[TensorLike] = nested_map(z, B.zeros_like)\n else:\n _baseline: Inputs[TensorLike] = many_of_om(_baseline)\n # Came from user; could have been single or multiple inputs.\n tensor_wrapper = TensorAKs(args=z)\n # Cast to either Tensor or numpy.ndarray to match what was given in z.\n return nested_cast(\n backend=B,\n args=_baseline,\n astype=type(tensor_wrapper.first_batchable(B))\n )\n
"},{"location":"trulens_explain/api/distributions/#trulens_explain.trulens.nn.distributions.LinearDoi.__init__","title":"
__init__(baseline=None, resolution=10, *, cut=None)","text":"
The DoI for point, z, will be a uniform distribution over the points on the line segment connecting z to baseline, approximated by a sample of resolution points equally spaced along this segment.
Parameters:
Name Type Description Default
cut Cut, optional, from DoI The Cut in which the DoI will be applied. If None, the DoI will be applied to the input. otherwise, the distribution should be applied to the latent space defined by the cut.
None baseline BaselineLike The baseline to interpolate from. Must be same shape as the space the distribution acts over, i.e., the shape of the points, z, eventually passed to __call__. If cut is None, this must be the same shape as the input, otherwise this must be the same shape as the latent space defined by the cut. If None is given, baseline will be the zero vector in the appropriate shape. If the baseline is callable, it is expected to return the baseline, given z and optional model arguments.
None resolution int Number of points returned by each call to this DoI. A higher resolution is more computationally expensive, but gives a better approximation of the DoI this object mathematically represents.
10 Source code in
trulens_explain/trulens/nn/distributions.py def __init__(\n self,\n baseline: BaselineLike = None,\n resolution: int = 10,\n *,\n cut: Cut = None,\n):\n\"\"\"\n The DoI for point, `z`, will be a uniform distribution over the points\n on the line segment connecting `z` to `baseline`, approximated by a\n sample of `resolution` points equally spaced along this segment.\n\n Parameters:\n cut (Cut, optional, from DoI): \n The Cut in which the DoI will be applied. If `None`, the DoI\n will be applied to the input. otherwise, the distribution should\n be applied to the latent space defined by the cut. \n baseline (BaselineLike, optional):\n The baseline to interpolate from. Must be same shape as the\n space the distribution acts over, i.e., the shape of the points,\n `z`, eventually passed to `__call__`. If `cut` is `None`, this\n must be the same shape as the input, otherwise this must be the\n same shape as the latent space defined by the cut. If `None` is\n given, `baseline` will be the zero vector in the appropriate\n shape. If the baseline is callable, it is expected to return the\n `baseline`, given `z` and optional model arguments.\n resolution (int):\n Number of points returned by each call to this DoI. A higher\n resolution is more computationally expensive, but gives a better\n approximation of the DoI this object mathematically represents.\n \"\"\"\n super(LinearDoi, self).__init__(cut)\n self._baseline = baseline\n self._resolution = resolution\n
"},{"location":"trulens_explain/api/distributions/#trulens_explain.trulens.nn.distributions.LinearDoi.get_activation_multiplier","title":"
get_activation_multiplier(activation, *, model_inputs=None)","text":"
Returns a term to multiply the gradient by to convert from \"influence space\" to \"attribution space\". Conceptually, \"influence space\" corresponds to the potential effect of a slight increase in each feature, while \"attribution space\" corresponds to an approximation of the net marginal contribution to the quantity of interest of each feature.
Parameters:
Name Type Description Default
activation OM[Inputs, TensorLike] The activation of the layer the DoI is applied to.
required
Returns:
Type Description
Inputs[TensorLike] The activation adjusted by the baseline passed to the constructor.
Source code in
trulens_explain/trulens/nn/distributions.py def get_activation_multiplier(\n self,\n activation: OM[Inputs, TensorLike],\n *,\n model_inputs: Optional[ModelInputs] = None\n) -> Inputs[TensorLike]:\n\"\"\"\n Returns a term to multiply the gradient by to convert from \"*influence \n space*\" to \"*attribution space*\". Conceptually, \"influence space\"\n corresponds to the potential effect of a slight increase in each \n feature, while \"attribution space\" corresponds to an approximation of\n the net marginal contribution to the quantity of interest of each \n feature.\n\n Parameters:\n activation:\n The activation of the layer the DoI is applied to.\n\n Returns:\n The activation adjusted by the baseline passed to the constructor.\n \"\"\"\n\n activation: Inputs[TensorLike] = many_of_om(activation)\n\n baseline: Inputs[TensorLike] = self._compute_baseline(\n activation, model_inputs=model_inputs\n )\n\n if baseline is None:\n return activation\n\n zipped = nested_zip(activation, baseline)\n\n def zipped_subtract(zipped_activation_baseline):\n\"\"\"subtracts zipped elements\n\n Args:\n zipped_activation_baseline: A tuple expecting the first element to be the activation, and second to be the baseline.\n\n Returns:\n a subtraction of activation and baseline\n \"\"\"\n activation = zipped_activation_baseline[0]\n baseline = zipped_activation_baseline[1]\n return activation - baseline\n\n ret = nested_map(zipped, zipped_subtract, check_accessor=lambda x: x[0])\n return ret\n
"},{"location":"trulens_explain/api/distributions/#trulens_explain.trulens.nn.distributions.PointDoi","title":"
PointDoi","text":"
Bases: DoI
Distribution that puts all probability mass on a single point.
Source code in
trulens_explain/trulens/nn/distributions.py class PointDoi(DoI):\n\"\"\"\n Distribution that puts all probability mass on a single point.\n \"\"\"\n\n def __init__(self, cut: Cut = None):\n\"\"\"\"Initialize PointDoI\n\n Parameters:\n cut (Cut, optional): \n The Cut in which the DoI will be applied. If `None`, the DoI will be\n applied to the input. otherwise, the distribution should be applied\n to the latent space defined by the cut. \n \"\"\"\n super(PointDoi, self).__init__(cut)\n\n def __call__(\n self,\n z: OM[Inputs, TensorLike],\n *,\n model_inputs: Optional[ModelInputs] = None\n ) -> OM[Inputs, Uniform[TensorLike]]:\n\n z: Inputs[TensorLike] = many_of_om(z)\n\n return om_of_many(nested_map(z, lambda x: [x]))\n
"},{"location":"trulens_explain/api/distributions/#trulens_explain.trulens.nn.distributions.PointDoi.__init__","title":"
__init__(cut=None)","text":"
\"Initialize PointDoI
Parameters:
Name Type Description Default
cut Cut The Cut in which the DoI will be applied. If None, the DoI will be applied to the input. otherwise, the distribution should be applied to the latent space defined by the cut.
None Source code in
trulens_explain/trulens/nn/distributions.py def __init__(self, cut: Cut = None):\n\"\"\"\"Initialize PointDoI\n\n Parameters:\n cut (Cut, optional): \n The Cut in which the DoI will be applied. If `None`, the DoI will be\n applied to the input. otherwise, the distribution should be applied\n to the latent space defined by the cut. \n \"\"\"\n super(PointDoi, self).__init__(cut)\n
"},{"location":"trulens_explain/api/model_wrappers/","title":"Model Wrappers","text":"
The TruLens library is designed to support models implemented via a variety of different popular python neural network frameworks: Keras (with TensorFlow or Theano backend), TensorFlow, and Pytorch. Models developed with different frameworks implement things (e.g., gradient computations) a number of different ways. We define framework specific ModelWrapper instances to create a unified model API, providing the same functionality to models that are implemented in disparate frameworks. In order to compute attributions for a model, we provide a trulens.nn.models.get_model_wrapper function that will return an appropriate ModelWrapper instance.
Some parameters are exclusively utilized for specific frameworks and are outlined in the parameter descriptions.
"},{"location":"trulens_explain/api/model_wrappers/#trulens_explain.trulens.nn.models.get_model_wrapper","title":"
get_model_wrapper(model, *, logit_layer=None, replace_softmax=False, softmax_layer=-1, custom_objects=None, device=None, input_tensors=None, output_tensors=None, internal_tensor_dict=None, default_feed_dict=None, session=None, backend=None, force_eval=True, **kwargs)","text":"
Returns a ModelWrapper implementation that exposes the components needed for computing attributions.
Parameters:
Name Type Description Default
model ModelLike The model to wrap. If using the TensorFlow 1 backend, this is expected to be a graph object.
required
logit_layer Supported for Keras and Pytorch models. Specifies the name or index of the layer that produces the logit predictions.
None replace_softmax bool Supported for Keras models only. If true, the activation function in the softmax layer (specified by softmax_layer) will be changed to a 'linear' activation.
False softmax_layer Supported for Keras models only. Specifies the layer that performs the softmax. This layer should have an activation attribute. Only used when replace_softmax is true.
-1 custom_objects Optional, for use with Keras models only. A dictionary of custom objects used by the Keras model.
None device str Optional, for use with Pytorch models only. A string specifying the device to run the model on.
None input_tensors Required for use with TensorFlow 1 graph models only. A list of tensors representing the input to the model graph.
None output_tensors Required for use with TensorFlow 1 graph models only. A list of tensors representing the output to the model graph.
None internal_tensor_dict Optional, for use with TensorFlow 1 graph models only. A dictionary mapping user-selected layer names to the internal tensors in the model graph that the user would like to expose. This is provided to give more human-readable names to the layers if desired. Internal tensors can also be accessed via the name given to them by tensorflow.
None default_feed_dict Optional, for use with TensorFlow 1 graph models only. A dictionary of default values to give to tensors in the model graph.
None session Optional, for use with TensorFlow 1 graph models only. A tf.Session object to run the model graph in. If None, a new temporary session will be generated every time the model is run.
None backend Optional, for forcing a specific backend. String values recognized are pytorch, tensorflow, keras, or tf.keras.
None force_eval _Optional, True will force a model.eval() call for PyTorch models. False will retain current model state
True Source code in
trulens_explain/trulens/nn/models/__init__.py def get_model_wrapper(\n model: ModelLike,\n *,\n logit_layer=None,\n replace_softmax: bool = False,\n softmax_layer=-1,\n custom_objects=None,\n device: str = None,\n input_tensors=None,\n output_tensors=None,\n internal_tensor_dict=None,\n default_feed_dict=None,\n session=None,\n backend=None,\n force_eval=True,\n **kwargs\n):\n\"\"\"\n Returns a ModelWrapper implementation that exposes the components needed for computing attributions.\n\n Parameters:\n model:\n The model to wrap. If using the TensorFlow 1 backend, this is \n expected to be a graph object.\n\n logit_layer:\n _Supported for Keras and Pytorch models._ \n Specifies the name or index of the layer that produces the\n logit predictions. \n\n replace_softmax:\n _Supported for Keras models only._ If true, the activation\n function in the softmax layer (specified by `softmax_layer`) \n will be changed to a `'linear'` activation. \n\n softmax_layer:\n _Supported for Keras models only._ Specifies the layer that\n performs the softmax. This layer should have an `activation`\n attribute. Only used when `replace_softmax` is true.\n\n custom_objects:\n _Optional, for use with Keras models only._ A dictionary of\n custom objects used by the Keras model.\n\n device:\n _Optional, for use with Pytorch models only._ A string\n specifying the device to run the model on.\n\n input_tensors:\n _Required for use with TensorFlow 1 graph models only._ A list\n of tensors representing the input to the model graph.\n\n output_tensors:\n _Required for use with TensorFlow 1 graph models only._ A list\n of tensors representing the output to the model graph.\n\n internal_tensor_dict:\n _Optional, for use with TensorFlow 1 graph models only._ A\n dictionary mapping user-selected layer names to the internal\n tensors in the model graph that the user would like to expose.\n This is provided to give more human-readable names to the layers\n if desired. Internal tensors can also be accessed via the name\n given to them by tensorflow.\n\n default_feed_dict:\n _Optional, for use with TensorFlow 1 graph models only._ A\n dictionary of default values to give to tensors in the model\n graph.\n\n session:\n _Optional, for use with TensorFlow 1 graph models only._ A \n `tf.Session` object to run the model graph in. If `None`, a new\n temporary session will be generated every time the model is run.\n\n backend:\n _Optional, for forcing a specific backend._ String values recognized\n are pytorch, tensorflow, keras, or tf.keras.\n\n force_eval:\n _Optional, True will force a model.eval() call for PyTorch models. False\n will retain current model state\n\n Returns: ModelWrapper\n \"\"\"\n\n if 'input_shape' in kwargs:\n tru_logger.deprecate(\n f\"get_model_wrapper: input_shape parameter is no longer used and will be removed in the future\"\n )\n del kwargs['input_shape']\n if 'input_dtype' in kwargs:\n tru_logger.deprecate(\n f\"get_model_wrapper: input_dtype parameter is no longer used and will be removed in the future\"\n )\n del kwargs['input_dtype']\n\n # get existing backend\n B = get_backend(suppress_warnings=True)\n\n if backend is None:\n backend = discern_backend(model)\n tru_logger.info(\n \"Detected {} backend for {}.\".format(\n backend.name.lower(), type(model)\n )\n )\n else:\n backend = Backend.from_name(backend)\n if B is None or (backend is not Backend.UNKNOWN and B.backend != backend):\n tru_logger.info(\n \"Changing backend from {} to {}.\".format(\n None if B is None else B.backend, backend\n )\n )\n os.environ['TRULENS_BACKEND'] = backend.name.lower()\n B = get_backend()\n else:\n tru_logger.info(\"Using backend {}.\".format(B.backend))\n tru_logger.info(\n \"If this seems incorrect, you can force the correct backend by passing the `backend` parameter directly into your get_model_wrapper call.\"\n )\n if B.backend.is_keras_derivative():\n from trulens.nn.models.keras import KerasModelWrapper\n return KerasModelWrapper(\n model,\n logit_layer=logit_layer,\n replace_softmax=replace_softmax,\n softmax_layer=softmax_layer,\n custom_objects=custom_objects\n )\n\n elif B.backend == Backend.PYTORCH:\n from trulens.nn.models.pytorch import PytorchModelWrapper\n return PytorchModelWrapper(\n model,\n logit_layer=logit_layer,\n device=device,\n force_eval=force_eval\n )\n elif B.backend == Backend.TENSORFLOW:\n import tensorflow as tf\n if tf.__version__.startswith('2'):\n from trulens.nn.models.tensorflow_v2 import Tensorflow2ModelWrapper\n return Tensorflow2ModelWrapper(\n model,\n logit_layer=logit_layer,\n replace_softmax=replace_softmax,\n softmax_layer=softmax_layer,\n custom_objects=custom_objects\n )\n else:\n from trulens.nn.models.tensorflow_v1 import TensorflowModelWrapper\n if input_tensors is None:\n tru_logger.error(\n 'tensorflow1 model must pass parameter: input_tensors'\n )\n if output_tensors is None:\n tru_logger.error(\n 'tensorflow1 model must pass parameter: output_tensors'\n )\n return TensorflowModelWrapper(\n model,\n input_tensors=input_tensors,\n output_tensors=output_tensors,\n internal_tensor_dict=internal_tensor_dict,\n session=session\n )\n
"},{"location":"trulens_explain/api/quantities/","title":"Quantities of Interest","text":"
A Quantity of Interest (QoI) is a function of the output that determines the network output behavior that the attributions describe.
The quantity of interest lets us specify what we want to explain. Often, this is the output of the network corresponding to a particular class, addressing, e.g., \"Why did the model classify a given image as a car?\" However, we could also consider various combinations of outputs, allowing us to ask more specific questions, such as, \"Why did the model classify a given image as a sedan and not a convertible?\" The former may highlight general \u201ccar features,\u201d such as tires, while the latter (called a comparative explanation) might focus on the roof of the car, a \u201ccar feature\u201d not shared by convertibles.
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.ClassQoI","title":"
ClassQoI","text":"
Bases: QoI
Quantity of interest for attributing output towards a specified class.
Source code in
trulens_explain/trulens/nn/quantities.py class ClassQoI(QoI):\n\"\"\"\n Quantity of interest for attributing output towards a specified class.\n \"\"\"\n\n def __init__(self, cl: int):\n\"\"\"\n Parameters:\n cl:\n The index of the class the QoI is for.\n \"\"\"\n self.cl = cl\n\n def __str__(self):\n return render_object(self, [\"cl\"])\n\n def __call__(self, y: TensorLike) -> TensorLike:\n self._assert_cut_contains_only_one_tensor(y)\n\n return y[:, self.cl]\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.ClassQoI.__init__","title":"
__init__(cl)","text":"
Parameters:
Name Type Description Default
cl int The index of the class the QoI is for.
required Source code in
trulens_explain/trulens/nn/quantities.py def __init__(self, cl: int):\n\"\"\"\n Parameters:\n cl:\n The index of the class the QoI is for.\n \"\"\"\n self.cl = cl\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.ClassSeqQoI","title":"
ClassSeqQoI","text":"
Bases: QoI
Quantity of interest for attributing output towards a sequence of classes for each input.
Source code in
trulens_explain/trulens/nn/quantities.py class ClassSeqQoI(QoI):\n\"\"\"\n Quantity of interest for attributing output towards a sequence of classes \n for each input.\n \"\"\"\n\n def __init__(self, seq_labels: List[int]):\n\"\"\"\n Parameters:\n seq_labels:\n A sequence of classes corresponding to each input.\n \"\"\"\n self.seq_labels = seq_labels\n\n def __call__(self, y):\n\n self._assert_cut_contains_only_one_tensor(y)\n assert get_backend().shape(y)[0] == len(self.seq_labels)\n\n return y[:, self.seq_labels]\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.ClassSeqQoI.__init__","title":"
__init__(seq_labels)","text":"
Parameters:
Name Type Description Default
seq_labels List[int] A sequence of classes corresponding to each input.
required Source code in
trulens_explain/trulens/nn/quantities.py def __init__(self, seq_labels: List[int]):\n\"\"\"\n Parameters:\n seq_labels:\n A sequence of classes corresponding to each input.\n \"\"\"\n self.seq_labels = seq_labels\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.ComparativeQoI","title":"
ComparativeQoI","text":"
Bases: QoI
Quantity of interest for attributing network output towards a given class, relative to another.
Source code in
trulens_explain/trulens/nn/quantities.py class ComparativeQoI(QoI):\n\"\"\"\n Quantity of interest for attributing network output towards a given class, \n relative to another.\n \"\"\"\n\n def __init__(self, cl1: int, cl2: int):\n\"\"\"\n Parameters:\n cl1:\n The index of the class the QoI is for.\n cl2:\n The index of the class to compare against.\n \"\"\"\n self.cl1 = cl1\n self.cl2 = cl2\n\n def __str__(self):\n return render_object(self, [\"cl1\", \"cl2\"])\n\n def __call__(self, y: TensorLike) -> TensorLike:\n\n self._assert_cut_contains_only_one_tensor(y)\n\n return y[:, self.cl1] - y[:, self.cl2]\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.ComparativeQoI.__init__","title":"
__init__(cl1, cl2)","text":"
Parameters:
Name Type Description Default
cl1 int The index of the class the QoI is for.
required
cl2 int The index of the class to compare against.
required Source code in
trulens_explain/trulens/nn/quantities.py def __init__(self, cl1: int, cl2: int):\n\"\"\"\n Parameters:\n cl1:\n The index of the class the QoI is for.\n cl2:\n The index of the class to compare against.\n \"\"\"\n self.cl1 = cl1\n self.cl2 = cl2\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.InternalChannelQoI","title":"
InternalChannelQoI","text":"
Bases: QoI
Quantity of interest for attributing output towards the output of an internal convolutional layer channel, aggregating using a specified operation.
Also works for non-convolutional dense layers, where the given neuron's activation is returned.
Source code in
trulens_explain/trulens/nn/quantities.py class InternalChannelQoI(QoI):\n\"\"\"\n Quantity of interest for attributing output towards the output of an \n internal convolutional layer channel, aggregating using a specified \n operation.\n\n Also works for non-convolutional dense layers, where the given neuron's\n activation is returned.\n \"\"\"\n\n @staticmethod\n def _batch_sum(x):\n\"\"\"\n Sums batched 2D channels, leaving the batch dimension unchanged.\n \"\"\"\n return get_backend().sum(x, axis=(1, 2))\n\n def __init__(\n self,\n channel: Union[int, List[int]],\n channel_axis: Optional[int] = None,\n agg_fn: Optional[Callable] = None\n ):\n\"\"\"\n Parameters:\n channel:\n Channel to return. If a list is provided, then the quantity sums \n over each of the channels in the list.\n\n channel_axis:\n Channel dimension index, if relevant, e.g., for 2D convolutional\n layers. If `channel_axis` is `None`, then the channel axis of \n the relevant backend will be used. This argument is not used \n when the channels are scalars, e.g., for dense layers.\n\n agg_fn:\n Function with which to aggregate the remaining dimensions \n (except the batch dimension) in order to get a single scalar \n value for each channel. If `agg_fn` is `None` then a sum over \n each neuron in the channel will be taken. This argument is not \n used when the channels are scalars, e.g., for dense layers.\n \"\"\"\n if channel_axis is None:\n channel_axis = get_backend().channel_axis\n if agg_fn is None:\n agg_fn = InternalChannelQoI._batch_sum\n\n self._channel_ax = channel_axis\n self._agg_fn = agg_fn\n self._channels = channel if isinstance(channel, list) else [channel]\n\n def __call__(self, y: TensorLike) -> TensorLike:\n B = get_backend()\n self._assert_cut_contains_only_one_tensor(y)\n\n if len(B.int_shape(y)) == 2:\n return sum([y[:, ch] for ch in self._channels])\n\n elif len(B.int_shape(y)) == 3:\n return sum([self._agg_fn(y[:, :, ch]) for ch in self._channel])\n\n elif len(B.int_shape(y)) == 4:\n if self._channel_ax == 1:\n return sum([self._agg_fn(y[:, ch]) for ch in self._channels])\n\n elif self._channel_ax == 3:\n return sum(\n [self._agg_fn(y[:, :, :, ch]) for ch in self._channels]\n )\n\n else:\n raise ValueError(\n 'Unsupported channel axis for convolutional layer: {}'.\n format(self._channel_ax)\n )\n\n else:\n raise QoiCutSupportError(\n 'Unsupported tensor rank for `InternalChannelQoI`: {}'.format(\n len(B.int_shape(y))\n )\n )\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.InternalChannelQoI.__init__","title":"
__init__(channel, channel_axis=None, agg_fn=None)","text":"
Parameters:
Name Type Description Default
channel Union[int, List[int]] Channel to return. If a list is provided, then the quantity sums over each of the channels in the list.
required
channel_axis Optional[int] Channel dimension index, if relevant, e.g., for 2D convolutional layers. If channel_axis is None, then the channel axis of the relevant backend will be used. This argument is not used when the channels are scalars, e.g., for dense layers.
None agg_fn Optional[Callable] Function with which to aggregate the remaining dimensions (except the batch dimension) in order to get a single scalar value for each channel. If agg_fn is None then a sum over each neuron in the channel will be taken. This argument is not used when the channels are scalars, e.g., for dense layers.
None Source code in
trulens_explain/trulens/nn/quantities.py def __init__(\n self,\n channel: Union[int, List[int]],\n channel_axis: Optional[int] = None,\n agg_fn: Optional[Callable] = None\n):\n\"\"\"\n Parameters:\n channel:\n Channel to return. If a list is provided, then the quantity sums \n over each of the channels in the list.\n\n channel_axis:\n Channel dimension index, if relevant, e.g., for 2D convolutional\n layers. If `channel_axis` is `None`, then the channel axis of \n the relevant backend will be used. This argument is not used \n when the channels are scalars, e.g., for dense layers.\n\n agg_fn:\n Function with which to aggregate the remaining dimensions \n (except the batch dimension) in order to get a single scalar \n value for each channel. If `agg_fn` is `None` then a sum over \n each neuron in the channel will be taken. This argument is not \n used when the channels are scalars, e.g., for dense layers.\n \"\"\"\n if channel_axis is None:\n channel_axis = get_backend().channel_axis\n if agg_fn is None:\n agg_fn = InternalChannelQoI._batch_sum\n\n self._channel_ax = channel_axis\n self._agg_fn = agg_fn\n self._channels = channel if isinstance(channel, list) else [channel]\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.LambdaQoI","title":"
LambdaQoI","text":"
Bases: QoI
Generic quantity of interest allowing the user to specify a function of the model's output as the QoI.
Source code in
trulens_explain/trulens/nn/quantities.py class LambdaQoI(QoI):\n\"\"\"\n Generic quantity of interest allowing the user to specify a function of the\n model's output as the QoI.\n \"\"\"\n\n def __init__(self, function: Callable):\n\"\"\"\n Parameters:\n function:\n A callable that takes a single argument representing the model's \n tensor output and returns a differentiable batched scalar tensor \n representing the QoI.\n \"\"\"\n if len(signature(function).parameters) != 1:\n raise ValueError(\n 'QoI function must take exactly 1 argument, but provided '\n 'function takes {} arguments'.format(\n len(signature(function).parameters)\n )\n )\n\n self.function = function\n\n def __call__(self, y: TensorLike) -> TensorLike:\n return self.function(y)\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.LambdaQoI.__init__","title":"
__init__(function)","text":"
Parameters:
Name Type Description Default
function Callable A callable that takes a single argument representing the model's tensor output and returns a differentiable batched scalar tensor representing the QoI.
required Source code in
trulens_explain/trulens/nn/quantities.py def __init__(self, function: Callable):\n\"\"\"\n Parameters:\n function:\n A callable that takes a single argument representing the model's \n tensor output and returns a differentiable batched scalar tensor \n representing the QoI.\n \"\"\"\n if len(signature(function).parameters) != 1:\n raise ValueError(\n 'QoI function must take exactly 1 argument, but provided '\n 'function takes {} arguments'.format(\n len(signature(function).parameters)\n )\n )\n\n self.function = function\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.MaxClassQoI","title":"
MaxClassQoI","text":"
Bases: QoI
Quantity of interest for attributing output towards the maximum-predicted class.
Source code in
trulens_explain/trulens/nn/quantities.py class MaxClassQoI(QoI):\n\"\"\"\n Quantity of interest for attributing output towards the maximum-predicted \n class.\n \"\"\"\n\n def __init__(\n self, axis: int = 1, activation: Union[Callable, str, None] = None\n ):\n\"\"\"\n Parameters:\n axis:\n Output dimension over which max operation is taken.\n\n activation:\n Activation function to be applied to the output before taking \n the max. If `activation` is a string, use the corresponding \n named activation function implemented by the backend. The \n following strings are currently supported as shorthands for the\n respective standard activation functions:\n\n - `'sigmoid'` \n - `'softmax'` \n\n If `activation` is `None`, no activation function is applied to\n the input.\n \"\"\"\n self._axis = axis\n self.activation = activation\n\n def __str__(self):\n return render_object(self, [\"_axis\", \"activation\"])\n\n def __call__(self, y: TensorLike) -> TensorLike:\n self._assert_cut_contains_only_one_tensor(y)\n\n if self.activation is not None:\n if isinstance(self.activation, str):\n self.activation = self.activation.lower()\n if self.activation in ['sigmoid', 'softmax']:\n y = getattr(get_backend(), self.activation)(y)\n\n else:\n raise NotImplementedError(\n 'This activation function is not currently supported '\n 'by the backend'\n )\n else:\n y = self.activation(y)\n\n return get_backend().max(y, axis=self._axis)\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.MaxClassQoI.__init__","title":"
__init__(axis=1, activation=None)","text":"
Parameters:
Name Type Description Default
axis int Output dimension over which max operation is taken.
1 activation Union[Callable, str, None] Activation function to be applied to the output before taking the max. If activation is a string, use the corresponding named activation function implemented by the backend. The following strings are currently supported as shorthands for the respective standard activation functions:
If activation is None, no activation function is applied to the input.
None Source code in
trulens_explain/trulens/nn/quantities.py def __init__(\n self, axis: int = 1, activation: Union[Callable, str, None] = None\n):\n\"\"\"\n Parameters:\n axis:\n Output dimension over which max operation is taken.\n\n activation:\n Activation function to be applied to the output before taking \n the max. If `activation` is a string, use the corresponding \n named activation function implemented by the backend. The \n following strings are currently supported as shorthands for the\n respective standard activation functions:\n\n - `'sigmoid'` \n - `'softmax'` \n\n If `activation` is `None`, no activation function is applied to\n the input.\n \"\"\"\n self._axis = axis\n self.activation = activation\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.QoI","title":"
QoI","text":"
Bases: AbstractBaseClass
Interface for quantities of interest. The Quantity of Interest (QoI) is a function of the output specified by the slice that determines the network output behavior that the attributions describe.
Source code in
trulens_explain/trulens/nn/quantities.py class QoI(AbstractBaseClass):\n\"\"\"\n Interface for quantities of interest. The *Quantity of Interest* (QoI) is a\n function of the output specified by the slice that determines the network \n output behavior that the attributions describe.\n \"\"\"\n\n def __str__(self):\n return render_object(self, [])\n\n # TODO: Need to give a seperate value of y at target instance here since\n # these are values are interventions. Cannot presently define a QoI that says:\n # logits of the predicted class for each instance.\n # Issue GH-72 . Task MLNN-415 .\n\n def _wrap_public_call(self, y: Outputs[Tensor]) -> Outputs[Tensor]:\n\"\"\"\n Wrap a public call that may result in one or more tensors. Signature of\n this class is not specific while public calls are flexible.\n \"\"\"\n\n return many_of_om(self.__call__(om_of_many(y)))\n\n @abstractmethod\n def __call__(self, y: OM[Outputs, Tensor]) -> OM[Outputs, Tensor]:\n\"\"\"\n Computes the distribution of interest from an initial point.\n\n Parameters:\n y:\n Output point from which the quantity is derived. Must be a\n differentiable tensor.\n\n Returns:\n A differentiable batched scalar tensor representing the QoI.\n \"\"\"\n raise NotImplementedError\n\n def _assert_cut_contains_only_one_tensor(self, x):\n if isinstance(x, DATA_CONTAINER_TYPE):\n raise QoiCutSupportError(\n 'Cut provided to quantity of interest was comprised of '\n 'multiple tensors, but `{}` is only defined for cuts comprised '\n 'of a single tensor (received a list of {} tensors).\\n'\n '\\n'\n 'Either (1) select a slice where the `to_cut` corresponds to a '\n 'single tensor, or (2) implement/use a `QoI` object that '\n 'supports lists of tensors, i.e., where the parameter, `x`, to '\n '`__call__` is expected/allowed to be a list of {} tensors.'.\n format(self.__class__.__name__, len(x), len(x))\n )\n\n elif not get_backend().is_tensor(x):\n raise ValueError(\n '`{}` expected to receive an instance of `Tensor`, but '\n 'received an instance of {}'.format(\n self.__class__.__name__, type(x)\n )\n )\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.QoI.__call__","title":"
__call__(y) abstractmethod","text":"
Computes the distribution of interest from an initial point.
Parameters:
Name Type Description Default
y OM[Outputs, Tensor] Output point from which the quantity is derived. Must be a differentiable tensor.
required
Returns:
Type Description
OM[Outputs, Tensor] A differentiable batched scalar tensor representing the QoI.
Source code in
trulens_explain/trulens/nn/quantities.py @abstractmethod\ndef __call__(self, y: OM[Outputs, Tensor]) -> OM[Outputs, Tensor]:\n\"\"\"\n Computes the distribution of interest from an initial point.\n\n Parameters:\n y:\n Output point from which the quantity is derived. Must be a\n differentiable tensor.\n\n Returns:\n A differentiable batched scalar tensor representing the QoI.\n \"\"\"\n raise NotImplementedError\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.QoiCutSupportError","title":"
QoiCutSupportError","text":"
Bases: ValueError
Exception raised if the quantity of interest is called on a cut whose output is not supported by the quantity of interest.
Source code in
trulens_explain/trulens/nn/quantities.py class QoiCutSupportError(ValueError):\n\"\"\"\n Exception raised if the quantity of interest is called on a cut whose output\n is not supported by the quantity of interest.\n \"\"\"\n pass\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.ThresholdQoI","title":"
ThresholdQoI","text":"
Bases: QoI
Quantity of interest for attributing network output toward the difference between two regions seperated by a given threshold. I.e., the quantity of interest is the \"high\" elements minus the \"low\" elements, where the high elements have activations above the threshold and the low elements have activations below the threshold.
Use case: bianry segmentation.
Source code in
trulens_explain/trulens/nn/quantities.py class ThresholdQoI(QoI):\n\"\"\"\n Quantity of interest for attributing network output toward the difference \n between two regions seperated by a given threshold. I.e., the quantity of\n interest is the \"high\" elements minus the \"low\" elements, where the high\n elements have activations above the threshold and the low elements have \n activations below the threshold.\n\n Use case: bianry segmentation.\n \"\"\"\n\n def __init__(\n self,\n threshold: float,\n low_minus_high: bool = False,\n activation: Union[Callable, str, None] = None\n ):\n\"\"\"\n Parameters:\n threshold:\n A threshold to determine the element-wise sign of the input \n tensor. The elements with activations higher than the threshold \n will retain their sign, while the elements with activations \n lower than the threshold will have their sign flipped (or vice \n versa if `low_minus_high` is set to `True`).\n low_minus_high:\n If `True`, substract the output with activations above the \n threshold from the output with activations below the threshold. \n If `False`, substract the output with activations below the \n threshold from the output with activations above the threshold.\n activation: str or function, optional\n Activation function to be applied to the quantity before taking\n the threshold. If `activation` is a string, use the \n corresponding activation function implemented by the backend \n (currently supported: `'sigmoid'` and `'softmax'`). Otherwise, \n if `activation` is not `None`, it will be treated as a callable.\n If `activation` is `None`, do not apply an activation function \n to the quantity.\n \"\"\"\n # TODO(klas):should this support an aggregation function? By default\n # this is a sum, but it could, for example, subtract the greatest\n # positive element from the least negative element.\n self.threshold = threshold\n self.low_minus_high = low_minus_high\n self.activation = activation\n\n def __call__(self, x: TensorLike) -> TensorLike:\n B = get_backend()\n self._assert_cut_contains_only_one_tensor(x)\n\n if self.activation is not None:\n if isinstance(self.activation, str):\n self.activation = self.activation.lower()\n if self.activation in ['sigmoid', 'softmax']:\n x = getattr(B, self.activation)(x)\n else:\n raise NotImplementedError(\n 'This activation function is not currently supported '\n 'by the backend'\n )\n else:\n x = self.activation(x)\n\n # TODO(klas): is the `clone` necessary here? Not sure why it was\n # included.\n mask = B.sign(B.clone(x) - self.threshold)\n if self.low_minus_high:\n mask = -mask\n\n non_batch_dimensions = tuple(range(len(B.int_shape(x)))[1:])\n\n return B.sum(mask * x, axis=non_batch_dimensions)\n
"},{"location":"trulens_explain/api/quantities/#trulens_explain.trulens.nn.quantities.ThresholdQoI.__init__","title":"
__init__(threshold, low_minus_high=False, activation=None)","text":"
Parameters:
Name Type Description Default
threshold float A threshold to determine the element-wise sign of the input tensor. The elements with activations higher than the threshold will retain their sign, while the elements with activations lower than the threshold will have their sign flipped (or vice versa if low_minus_high is set to True).
required
low_minus_high bool If True, substract the output with activations above the threshold from the output with activations below the threshold. If False, substract the output with activations below the threshold from the output with activations above the threshold.
False activation Union[Callable, str, None] str or function, optional Activation function to be applied to the quantity before taking the threshold. If activation is a string, use the corresponding activation function implemented by the backend (currently supported: 'sigmoid' and 'softmax'). Otherwise, if activation is not None, it will be treated as a callable. If activation is None, do not apply an activation function to the quantity.
None Source code in
trulens_explain/trulens/nn/quantities.py def __init__(\n self,\n threshold: float,\n low_minus_high: bool = False,\n activation: Union[Callable, str, None] = None\n):\n\"\"\"\n Parameters:\n threshold:\n A threshold to determine the element-wise sign of the input \n tensor. The elements with activations higher than the threshold \n will retain their sign, while the elements with activations \n lower than the threshold will have their sign flipped (or vice \n versa if `low_minus_high` is set to `True`).\n low_minus_high:\n If `True`, substract the output with activations above the \n threshold from the output with activations below the threshold. \n If `False`, substract the output with activations below the \n threshold from the output with activations above the threshold.\n activation: str or function, optional\n Activation function to be applied to the quantity before taking\n the threshold. If `activation` is a string, use the \n corresponding activation function implemented by the backend \n (currently supported: `'sigmoid'` and `'softmax'`). Otherwise, \n if `activation` is not `None`, it will be treated as a callable.\n If `activation` is `None`, do not apply an activation function \n to the quantity.\n \"\"\"\n # TODO(klas):should this support an aggregation function? By default\n # this is a sum, but it could, for example, subtract the greatest\n # positive element from the least negative element.\n self.threshold = threshold\n self.low_minus_high = low_minus_high\n self.activation = activation\n
"},{"location":"trulens_explain/api/slices/","title":"Slices","text":"
The slice, or layer, of the network provides flexibility over the level of abstraction for the explanation. In a low layer, an explanation may highlight the edges that were most important in identifying an object like a face, while in a higher layer, the explanation might highlight high-level features such as a nose or mouth. By raising the level of abstraction, explanations that generalize over larger sets of samples are possible.
Formally, A network, \\(f\\), can be broken into a slice, \\(f = g \\circ h\\), where \\(h\\) can be thought of as a pre-processor that computes features, and \\(g\\) can be thought of as a sub-model that uses the features computed by \\(h\\).
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.Cut","title":"
Cut","text":"
Bases: object
A cut is the primary building block for a slice. It determines an internal component of a network to expose. A slice if formed by two cuts.
Source code in
trulens_explain/trulens/nn/slices.py class Cut(object):\n\"\"\"\n A cut is the primary building block for a slice. It determines an internal\n component of a network to expose. A slice if formed by two cuts.\n \"\"\"\n\n def __init__(\n self,\n name: LayerIdentifier,\n anchor: str = 'out',\n accessor: Optional[Callable] = None\n ):\n\"\"\"\n Parameters:\n name:\n The name or index of a layer in the model, or a list containing\n the names/indices of mutliple layers.\n\n anchor: \n Determines whether input (`'in'`) or the output (`'out'`) tensor\n of the spcified layer should be used.\n\n accessor:\n An accessor function that operates on the layer, mapping the \n tensor (or list thereof) corresponding to the layer's \n input/output to another tensor (or list thereof). This can be \n used to, e.g., extract a particular output from a layer that \n produces a sequence of outputs. If `accessor` is `None`, the \n following accessor function will be used: \n ```python\n lambda t: t[-1] if isinstance(t, list) else t\n ```\n \"\"\"\n assert name is None or isinstance(\n name, (list, int, str)\n ), \"Cut.name must be one of: layer index, layer name, or list of names/indices of multiple layers\"\n if isinstance(name, list):\n for n in name:\n assert isinstance(\n n, (int, str)\n ), f\"Elements in Cut.name must be layer names (str) or indices (int). Got type {type(n)}\"\n anchor = str(anchor)\n assert anchor in [\n 'in', 'out'\n ], \"Cut.anchor must be one of ('in', 'out')\"\n assert accessor is None or isinstance(\n accessor, Callable\n ), \"Cut.accessor must be callable or None\"\n\n if get_backend().backend == 'pytorch':\n if (isinstance(name, int) or\n (isinstance(name, list) and isinstance(name[0], int))):\n\n tru_logger.warning(\n '\\n\\nPytorch does not have native support for indexed '\n 'layers. Using layer indices is not recommended.\\n'\n )\n\n self.name = name\n self.accessor = accessor\n self.anchor = anchor\n\n def __str__(self):\n return render_object(self, ['name', 'accessor', 'anchor'])\n\n # TODO: layer arg might need to be more specific\n def access_layer(self, layer: TensorLike) -> TensorLike:\n\"\"\"\n Applies `self.accessor` to the result of collecting the relevant \n tensor(s) associated with a layer's output.\n\n Parameters:\n layer:\n The tensor output (or input, if so specified by the anchor) of \n the layer(s) specified by this cut.\n\n Returns:\n The result of applying `self.accessor` to the given layer.\n \"\"\"\n if layer is None:\n return layer\n elif self.accessor is None:\n return layer\n else:\n layer = (\n layer[0]\n if isinstance(layer, list) and len(layer) == 1 else layer\n )\n return self.accessor(layer)\n
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.Cut.__init__","title":"
__init__(name, anchor='out', accessor=None)","text":"
Parameters:
Name Type Description Default
name LayerIdentifier The name or index of a layer in the model, or a list containing the names/indices of mutliple layers.
required
anchor str Determines whether input ('in') or the output ('out') tensor of the spcified layer should be used.
'out' accessor Optional[Callable] An accessor function that operates on the layer, mapping the tensor (or list thereof) corresponding to the layer's input/output to another tensor (or list thereof). This can be used to, e.g., extract a particular output from a layer that produces a sequence of outputs. If accessor is None, the following accessor function will be used:
lambda t: t[-1] if isinstance(t, list) else t\n
None Source code in
trulens_explain/trulens/nn/slices.py def __init__(\n self,\n name: LayerIdentifier,\n anchor: str = 'out',\n accessor: Optional[Callable] = None\n):\n\"\"\"\n Parameters:\n name:\n The name or index of a layer in the model, or a list containing\n the names/indices of mutliple layers.\n\n anchor: \n Determines whether input (`'in'`) or the output (`'out'`) tensor\n of the spcified layer should be used.\n\n accessor:\n An accessor function that operates on the layer, mapping the \n tensor (or list thereof) corresponding to the layer's \n input/output to another tensor (or list thereof). This can be \n used to, e.g., extract a particular output from a layer that \n produces a sequence of outputs. If `accessor` is `None`, the \n following accessor function will be used: \n ```python\n lambda t: t[-1] if isinstance(t, list) else t\n ```\n \"\"\"\n assert name is None or isinstance(\n name, (list, int, str)\n ), \"Cut.name must be one of: layer index, layer name, or list of names/indices of multiple layers\"\n if isinstance(name, list):\n for n in name:\n assert isinstance(\n n, (int, str)\n ), f\"Elements in Cut.name must be layer names (str) or indices (int). Got type {type(n)}\"\n anchor = str(anchor)\n assert anchor in [\n 'in', 'out'\n ], \"Cut.anchor must be one of ('in', 'out')\"\n assert accessor is None or isinstance(\n accessor, Callable\n ), \"Cut.accessor must be callable or None\"\n\n if get_backend().backend == 'pytorch':\n if (isinstance(name, int) or\n (isinstance(name, list) and isinstance(name[0], int))):\n\n tru_logger.warning(\n '\\n\\nPytorch does not have native support for indexed '\n 'layers. Using layer indices is not recommended.\\n'\n )\n\n self.name = name\n self.accessor = accessor\n self.anchor = anchor\n
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.Cut.access_layer","title":"
access_layer(layer)","text":"
Applies self.accessor to the result of collecting the relevant tensor(s) associated with a layer's output.
Parameters:
Name Type Description Default
layer TensorLike The tensor output (or input, if so specified by the anchor) of the layer(s) specified by this cut.
required
Returns:
Type Description
TensorLike The result of applying self.accessor to the given layer.
Source code in
trulens_explain/trulens/nn/slices.py def access_layer(self, layer: TensorLike) -> TensorLike:\n\"\"\"\n Applies `self.accessor` to the result of collecting the relevant \n tensor(s) associated with a layer's output.\n\n Parameters:\n layer:\n The tensor output (or input, if so specified by the anchor) of \n the layer(s) specified by this cut.\n\n Returns:\n The result of applying `self.accessor` to the given layer.\n \"\"\"\n if layer is None:\n return layer\n elif self.accessor is None:\n return layer\n else:\n layer = (\n layer[0]\n if isinstance(layer, list) and len(layer) == 1 else layer\n )\n return self.accessor(layer)\n
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.InputCut","title":"
InputCut","text":"
Bases: Cut
Special cut that selects the input(s) of a model.
Source code in
trulens_explain/trulens/nn/slices.py class InputCut(Cut):\n\"\"\"\n Special cut that selects the input(s) of a model.\n \"\"\"\n\n def __init__(self, anchor: str = 'in', accessor: Optional[Callable] = None):\n\"\"\"\n Parameters:\n anchor: \n Determines whether input (`'in'`) or the output (`'out'`) tensor\n of the spcified layer should be used.\n\n accessor:\n An accessor function that operates on the layer, mapping the \n tensor (or list thereof) corresponding to the layer's \n input/output to another tensor (or list thereof). This can be \n used to, e.g., extract a particular output from a layer that \n produces a sequence of outputs. If `accessor` is `None`, the \n following accessor function will be used: \n ```python\n lambda t: t[-1] if isinstance(t, list) else t\n ```\n \"\"\"\n super().__init__(None, anchor, accessor)\n
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.InputCut.__init__","title":"
__init__(anchor='in', accessor=None)","text":"
Parameters:
Name Type Description Default
anchor str Determines whether input ('in') or the output ('out') tensor of the spcified layer should be used.
'in' accessor Optional[Callable] An accessor function that operates on the layer, mapping the tensor (or list thereof) corresponding to the layer's input/output to another tensor (or list thereof). This can be used to, e.g., extract a particular output from a layer that produces a sequence of outputs. If accessor is None, the following accessor function will be used:
lambda t: t[-1] if isinstance(t, list) else t\n
None Source code in
trulens_explain/trulens/nn/slices.py def __init__(self, anchor: str = 'in', accessor: Optional[Callable] = None):\n\"\"\"\n Parameters:\n anchor: \n Determines whether input (`'in'`) or the output (`'out'`) tensor\n of the spcified layer should be used.\n\n accessor:\n An accessor function that operates on the layer, mapping the \n tensor (or list thereof) corresponding to the layer's \n input/output to another tensor (or list thereof). This can be \n used to, e.g., extract a particular output from a layer that \n produces a sequence of outputs. If `accessor` is `None`, the \n following accessor function will be used: \n ```python\n lambda t: t[-1] if isinstance(t, list) else t\n ```\n \"\"\"\n super().__init__(None, anchor, accessor)\n
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.LogitCut","title":"
LogitCut","text":"
Bases: Cut
Special cut that selects the logit layer of a model. The logit layer must be named 'logits' or otherwise specified by the user to the model wrapper.
Source code in
trulens_explain/trulens/nn/slices.py class LogitCut(Cut):\n\"\"\"\n Special cut that selects the logit layer of a model. The logit layer must be\n named `'logits'` or otherwise specified by the user to the model wrapper.\n \"\"\"\n\n def __init__(\n self, anchor: str = 'out', accessor: Optional[Callable] = None\n ):\n\"\"\"\n Parameters:\n anchor: \n Determines whether input (`'in'`) or the output (`'out'`) tensor\n of the spcified layer should be used.\n\n accessor:\n An accessor function that operates on the layer, mapping the \n tensor (or list thereof) corresponding to the layer's \n input/output to another tensor (or list thereof). This can be \n used to, e.g., extract a particular output from a layer that \n produces a sequence of outputs. If `accessor` is `None`, the \n following accessor function will be used: \n ```python\n lambda t: t[-1] if isinstance(t, list) else t\n ```\n \"\"\"\n super(LogitCut, self).__init__(None, anchor, accessor)\n
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.LogitCut.__init__","title":"
__init__(anchor='out', accessor=None)","text":"
Parameters:
Name Type Description Default
anchor str Determines whether input ('in') or the output ('out') tensor of the spcified layer should be used.
'out' accessor Optional[Callable] An accessor function that operates on the layer, mapping the tensor (or list thereof) corresponding to the layer's input/output to another tensor (or list thereof). This can be used to, e.g., extract a particular output from a layer that produces a sequence of outputs. If accessor is None, the following accessor function will be used:
lambda t: t[-1] if isinstance(t, list) else t\n
None Source code in
trulens_explain/trulens/nn/slices.py def __init__(\n self, anchor: str = 'out', accessor: Optional[Callable] = None\n):\n\"\"\"\n Parameters:\n anchor: \n Determines whether input (`'in'`) or the output (`'out'`) tensor\n of the spcified layer should be used.\n\n accessor:\n An accessor function that operates on the layer, mapping the \n tensor (or list thereof) corresponding to the layer's \n input/output to another tensor (or list thereof). This can be \n used to, e.g., extract a particular output from a layer that \n produces a sequence of outputs. If `accessor` is `None`, the \n following accessor function will be used: \n ```python\n lambda t: t[-1] if isinstance(t, list) else t\n ```\n \"\"\"\n super(LogitCut, self).__init__(None, anchor, accessor)\n
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.OutputCut","title":"
OutputCut","text":"
Bases: Cut
Special cut that selects the output(s) of a model.
Source code in
trulens_explain/trulens/nn/slices.py class OutputCut(Cut):\n\"\"\"\n Special cut that selects the output(s) of a model.\n \"\"\"\n\n def __init__(\n self, anchor: str = 'out', accessor: Optional[Callable] = None\n ):\n\"\"\"\n Parameters:\n anchor: \n Determines whether input (`'in'`) or the output (`'out'`) tensor\n of the spcified layer should be used.\n\n accessor:\n An accessor function that operates on the layer, mapping the \n tensor (or list thereof) corresponding to the layer's \n input/output to another tensor (or list thereof). This can be \n used to, e.g., extract a particular output from a layer that \n produces a sequence of outputs. If `accessor` is `None`, the \n following accessor function will be used: \n ```python\n lambda t: t[-1] if isinstance(t, list) else t\n ```\n \"\"\"\n super(OutputCut, self).__init__(None, anchor, accessor)\n
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.OutputCut.__init__","title":"
__init__(anchor='out', accessor=None)","text":"
Parameters:
Name Type Description Default
anchor str Determines whether input ('in') or the output ('out') tensor of the spcified layer should be used.
'out' accessor Optional[Callable] An accessor function that operates on the layer, mapping the tensor (or list thereof) corresponding to the layer's input/output to another tensor (or list thereof). This can be used to, e.g., extract a particular output from a layer that produces a sequence of outputs. If accessor is None, the following accessor function will be used:
lambda t: t[-1] if isinstance(t, list) else t\n
None Source code in
trulens_explain/trulens/nn/slices.py def __init__(\n self, anchor: str = 'out', accessor: Optional[Callable] = None\n):\n\"\"\"\n Parameters:\n anchor: \n Determines whether input (`'in'`) or the output (`'out'`) tensor\n of the spcified layer should be used.\n\n accessor:\n An accessor function that operates on the layer, mapping the \n tensor (or list thereof) corresponding to the layer's \n input/output to another tensor (or list thereof). This can be \n used to, e.g., extract a particular output from a layer that \n produces a sequence of outputs. If `accessor` is `None`, the \n following accessor function will be used: \n ```python\n lambda t: t[-1] if isinstance(t, list) else t\n ```\n \"\"\"\n super(OutputCut, self).__init__(None, anchor, accessor)\n
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.Slice","title":"
Slice","text":"
Bases: object
Class representing a slice of a network. A network, \\(f\\), can be broken into a slice, \\(f = g \\circ h\\), where \\(h\\) can be thought of as a pre-processor that computes features, and \\(g\\) can be thought of as a sub-model that uses the features computed by \\(h\\).
A Slice object represents a slice as two Cuts, from_cut and to_cut, which are the layers corresponding to the output of \\(h\\) and \\(g\\), respectively.
Source code in
trulens_explain/trulens/nn/slices.py class Slice(object):\n\"\"\"\n Class representing a slice of a network. A network, $f$, can be broken\n into a slice, $f = g \\\\circ h$, where $h$ can be thought of as a \n pre-processor that computes features, and $g$ can be thought of as a \n sub-model that uses the features computed by $h$.\n\n A `Slice` object represents a slice as two `Cut`s, `from_cut` and `to_cut`,\n which are the layers corresponding to the output of $h$ and $g$, \n respectively.\n \"\"\"\n\n def __init__(self, from_cut: Cut, to_cut: Cut):\n\"\"\"\n Parameters:\n from_cut:\n Cut representing the output of the preprocessing function, $h$,\n in slice, $f = g \\\\circ h$.\n\n to_cut:\n Cut representing the output of the sub-model, $g$, in slice, \n $f = g \\\\circ h$.\n \"\"\"\n self._from_cut = from_cut\n self._to_cut = to_cut\n\n @property\n def from_cut(self) -> Cut:\n\"\"\"\n Cut representing the output of the preprocessing function, $h$, in \n slice, $f = g \\\\circ h$.\n \"\"\"\n return self._from_cut\n\n @property\n def to_cut(self) -> Cut:\n\"\"\"\n Cut representing the output of the sub-model, $g$, in slice, \n $f = g \\\\circ h$.\n \"\"\"\n return self._to_cut\n\n @staticmethod\n def full_network():\n\"\"\"\n Returns\n -------\n Slice\n A slice representing the entire model, i.e., :math:`f = g \\\\circ h`,\n where :math:`h` is the identity function and :math:`g = f`.\n \"\"\"\n return Slice(InputCut(), OutputCut())\n
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.Slice.from_cut","title":"
from_cut: Cut property","text":"
Cut representing the output of the preprocessing function, \\(h\\), in slice, \\(f = g \\circ h\\).
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.Slice.to_cut","title":"
to_cut: Cut property","text":"
Cut representing the output of the sub-model, \\(g\\), in slice, \\(f = g \\circ h\\).
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.Slice.__init__","title":"
__init__(from_cut, to_cut)","text":"
Parameters:
Name Type Description Default
from_cut Cut Cut representing the output of the preprocessing function, \\(h\\), in slice, \\(f = g \\circ h\\).
required
to_cut Cut Cut representing the output of the sub-model, \\(g\\), in slice, \\(f = g \\circ h\\).
required Source code in
trulens_explain/trulens/nn/slices.py def __init__(self, from_cut: Cut, to_cut: Cut):\n\"\"\"\n Parameters:\n from_cut:\n Cut representing the output of the preprocessing function, $h$,\n in slice, $f = g \\\\circ h$.\n\n to_cut:\n Cut representing the output of the sub-model, $g$, in slice, \n $f = g \\\\circ h$.\n \"\"\"\n self._from_cut = from_cut\n self._to_cut = to_cut\n
"},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.Slice.full_network","title":"
full_network() staticmethod","text":""},{"location":"trulens_explain/api/slices/#trulens_explain.trulens.nn.slices.Slice.full_network--returns","title":"Returns","text":"
Slice A slice representing the entire model, i.e., :math:f = g \\circ h, where :math:h is the identity function and :math:g = f.
Source code in
trulens_explain/trulens/nn/slices.py @staticmethod\ndef full_network():\n\"\"\"\n Returns\n -------\n Slice\n A slice representing the entire model, i.e., :math:`f = g \\\\circ h`,\n where :math:`h` is the identity function and :math:`g = f`.\n \"\"\"\n return Slice(InputCut(), OutputCut())\n
"},{"location":"trulens_explain/api/visualizations/","title":"Visualization Methods","text":"
One clear use case for measuring attributions is for human consumption. In order to be fully leveraged by humans, explanations need to be interpretable \u2014 a large vector of numbers doesn\u2019t in general make us more confident we understand what a network is doing. We therefore view an explanation as comprised of both an attribution measurement and an interpretation of what the attribution values represent.
One obvious way to interpret attributions, particularly in the image domain, is via visualization. This module provides several visualization methods for interpreting attributions as images.
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.ChannelMaskVisualizer","title":"
ChannelMaskVisualizer","text":"
Bases: object
Uses internal influence to visualize the pixels that are most salient towards a particular internal channel or neuron.
Source code in
trulens_explain/trulens/visualizations.py class ChannelMaskVisualizer(object):\n\"\"\"\n Uses internal influence to visualize the pixels that are most salient\n towards a particular internal channel or neuron.\n \"\"\"\n\n def __init__(\n self,\n model,\n layer,\n channel,\n channel_axis=None,\n agg_fn=None,\n doi=None,\n blur=None,\n threshold=0.5,\n masked_opacity=0.2,\n combine_channels: bool = True,\n use_attr_as_opacity=None,\n positive_only=None\n ):\n\"\"\"\n Configures the default parameters for the `__call__` method (these can \n be overridden by passing in values to `__call__`).\n\n Parameters:\n model:\n The wrapped model whose channel we're visualizing.\n\n layer:\n The identifier (either index or name) of the layer in which the \n channel we're visualizing resides.\n\n channel:\n Index of the channel (for convolutional layers) or internal \n neuron (for fully-connected layers) that we'd like to visualize.\n\n channel_axis:\n If different from the channel axis specified by the backend, the\n supplied `channel_axis` will be used if operating on a \n convolutional layer with 4-D image format.\n\n agg_fn:\n Function with which to aggregate the remaining dimensions \n (except the batch dimension) in order to get a single scalar \n value for each channel; If `None`, a sum over each neuron in the\n channel will be taken. This argument is not used when the \n channels are scalars, e.g., for dense layers.\n\n doi:\n The distribution of interest to use when computing the input\n attributions towards the specified channel. If `None`, \n `PointDoI` will be used.\n\n blur:\n Gives the radius of a Gaussian blur to be applied to the \n attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels.\n\n threshold:\n Value in the range [0, 1]. Attribution values at or below the \n percentile given by `threshold` (after normalization, blurring,\n etc.) will be masked.\n\n masked_opacity: \n Value in the range [0, 1] specifying the opacity for the parts\n of the image that are masked.\n\n combine_channels:\n If `True`, the attributions will be averaged across the channel\n dimension, resulting in a 1-channel attribution map.\n\n use_attr_as_opacity:\n If `True`, instead of using `threshold` and `masked_opacity`,\n the opacity of each pixel is given by the 0-1-normalized \n attribution value.\n\n positive_only:\n If `True`, only pixels with positive attribution will be \n unmasked (or given nonzero opacity when `use_attr_as_opacity` is\n true).\n \"\"\"\n B = get_backend()\n if (B is not None and (channel_axis is None or channel_axis < 0)):\n channel_axis = B.channel_axis\n elif (channel_axis is None or channel_axis < 0):\n channel_axis = 1\n\n self.mask_visualizer = MaskVisualizer(\n blur, threshold, masked_opacity, combine_channels,\n use_attr_as_opacity, positive_only\n )\n\n self.infl_input = InternalInfluence(\n model, (InputCut(), Cut(layer)),\n InternalChannelQoI(channel, channel_axis, agg_fn),\n PointDoi() if doi is None else doi\n )\n\n def __call__(\n self,\n x,\n x_preprocessed=None,\n output_file=None,\n blur=None,\n threshold=None,\n masked_opacity=None,\n combine_channels=None\n ):\n\"\"\"\n Visualizes the given attributions by overlaying an attribution heatmap \n over the given image.\n\n Parameters\n ----------\n attributions : numpy.ndarray\n The attributions to visualize. Expected to be in 4-D image format.\n\n x : numpy.ndarray\n The original image(s) over which the attributions are calculated.\n Must be the same shape as expected by the model used with this\n visualizer.\n\n x_preprocessed : numpy.ndarray, optional\n If the model requires a preprocessed input (e.g., with the mean\n subtracted) that is different from how the image should be \n visualized, ``x_preprocessed`` should be specified. In this case \n ``x`` will be used for visualization, and ``x_preprocessed`` will be\n passed to the model when calculating attributions. Must be the same \n shape as ``x``.\n\n output_file : str, optional\n If specified, the resulting visualization will be saved to a file\n with the name given by ``output_file``.\n\n blur : float, optional\n If specified, gives the radius of a Gaussian blur to be applied to\n the attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels. If None, \n defaults to the value supplied to the constructor. Default None.\n\n threshold : float\n Value in the range [0, 1]. Attribution values at or below the \n percentile given by ``threshold`` will be masked. If None, defaults \n to the value supplied to the constructor. Default None.\n\n masked_opacity: float\n Value in the range [0, 1] specifying the opacity for the parts of\n the image that are masked. Default 0.2. If None, defaults to the \n value supplied to the constructor. Default None.\n\n combine_channels : bool\n If True, the attributions will be averaged across the channel\n dimension, resulting in a 1-channel attribution map. If None, \n defaults to the value supplied to the constructor. Default None.\n \"\"\"\n\n attrs_input = self.infl_input.attributions(\n x if x_preprocessed is None else x_preprocessed\n )\n\n return self.mask_visualizer(\n attrs_input, x, output_file, blur, threshold, masked_opacity,\n combine_channels\n )\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.ChannelMaskVisualizer.__call__","title":"
__call__(x, x_preprocessed=None, output_file=None, blur=None, threshold=None, masked_opacity=None, combine_channels=None)","text":"
Visualizes the given attributions by overlaying an attribution heatmap over the given image.
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.ChannelMaskVisualizer.__call__--parameters","title":"Parameters","text":"numpy.ndarray
The attributions to visualize. Expected to be in 4-D image format.
numpy.ndarray
The original image(s) over which the attributions are calculated. Must be the same shape as expected by the model used with this visualizer.
numpy.ndarray, optional
If the model requires a preprocessed input (e.g., with the mean subtracted) that is different from how the image should be visualized, x_preprocessed should be specified. In this case x will be used for visualization, and x_preprocessed will be passed to the model when calculating attributions. Must be the same shape as x.
str, optional
If specified, the resulting visualization will be saved to a file with the name given by output_file.
float, optional
If specified, gives the radius of a Gaussian blur to be applied to the attributions before visualizing. This can be used to help focus on salient regions rather than specific salient pixels. If None, defaults to the value supplied to the constructor. Default None.
float
Value in the range [0, 1]. Attribution values at or below the percentile given by threshold will be masked. If None, defaults to the value supplied to the constructor. Default None.
float
Value in the range [0, 1] specifying the opacity for the parts of the image that are masked. Default 0.2. If None, defaults to the value supplied to the constructor. Default None.
bool
If True, the attributions will be averaged across the channel dimension, resulting in a 1-channel attribution map. If None, defaults to the value supplied to the constructor. Default None.
Source code in
trulens_explain/trulens/visualizations.py def __call__(\n self,\n x,\n x_preprocessed=None,\n output_file=None,\n blur=None,\n threshold=None,\n masked_opacity=None,\n combine_channels=None\n):\n\"\"\"\n Visualizes the given attributions by overlaying an attribution heatmap \n over the given image.\n\n Parameters\n ----------\n attributions : numpy.ndarray\n The attributions to visualize. Expected to be in 4-D image format.\n\n x : numpy.ndarray\n The original image(s) over which the attributions are calculated.\n Must be the same shape as expected by the model used with this\n visualizer.\n\n x_preprocessed : numpy.ndarray, optional\n If the model requires a preprocessed input (e.g., with the mean\n subtracted) that is different from how the image should be \n visualized, ``x_preprocessed`` should be specified. In this case \n ``x`` will be used for visualization, and ``x_preprocessed`` will be\n passed to the model when calculating attributions. Must be the same \n shape as ``x``.\n\n output_file : str, optional\n If specified, the resulting visualization will be saved to a file\n with the name given by ``output_file``.\n\n blur : float, optional\n If specified, gives the radius of a Gaussian blur to be applied to\n the attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels. If None, \n defaults to the value supplied to the constructor. Default None.\n\n threshold : float\n Value in the range [0, 1]. Attribution values at or below the \n percentile given by ``threshold`` will be masked. If None, defaults \n to the value supplied to the constructor. Default None.\n\n masked_opacity: float\n Value in the range [0, 1] specifying the opacity for the parts of\n the image that are masked. Default 0.2. If None, defaults to the \n value supplied to the constructor. Default None.\n\n combine_channels : bool\n If True, the attributions will be averaged across the channel\n dimension, resulting in a 1-channel attribution map. If None, \n defaults to the value supplied to the constructor. Default None.\n \"\"\"\n\n attrs_input = self.infl_input.attributions(\n x if x_preprocessed is None else x_preprocessed\n )\n\n return self.mask_visualizer(\n attrs_input, x, output_file, blur, threshold, masked_opacity,\n combine_channels\n )\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.ChannelMaskVisualizer.__init__","title":"
__init__(model, layer, channel, channel_axis=None, agg_fn=None, doi=None, blur=None, threshold=0.5, masked_opacity=0.2, combine_channels=True, use_attr_as_opacity=None, positive_only=None)","text":"
Configures the default parameters for the __call__ method (these can be overridden by passing in values to __call__).
Parameters:
Name Type Description Default
model The wrapped model whose channel we're visualizing.
required
layer The identifier (either index or name) of the layer in which the channel we're visualizing resides.
required
channel Index of the channel (for convolutional layers) or internal neuron (for fully-connected layers) that we'd like to visualize.
required
channel_axis If different from the channel axis specified by the backend, the supplied channel_axis will be used if operating on a convolutional layer with 4-D image format.
None agg_fn Function with which to aggregate the remaining dimensions (except the batch dimension) in order to get a single scalar value for each channel; If None, a sum over each neuron in the channel will be taken. This argument is not used when the channels are scalars, e.g., for dense layers.
None doi The distribution of interest to use when computing the input attributions towards the specified channel. If None, PointDoI will be used.
None blur Gives the radius of a Gaussian blur to be applied to the attributions before visualizing. This can be used to help focus on salient regions rather than specific salient pixels.
None threshold Value in the range [0, 1]. Attribution values at or below the percentile given by threshold (after normalization, blurring, etc.) will be masked.
0.5 masked_opacity Value in the range [0, 1] specifying the opacity for the parts of the image that are masked.
0.2 combine_channels bool If True, the attributions will be averaged across the channel dimension, resulting in a 1-channel attribution map.
True use_attr_as_opacity If True, instead of using threshold and masked_opacity, the opacity of each pixel is given by the 0-1-normalized attribution value.
None positive_only If True, only pixels with positive attribution will be unmasked (or given nonzero opacity when use_attr_as_opacity is true).
None Source code in
trulens_explain/trulens/visualizations.py def __init__(\n self,\n model,\n layer,\n channel,\n channel_axis=None,\n agg_fn=None,\n doi=None,\n blur=None,\n threshold=0.5,\n masked_opacity=0.2,\n combine_channels: bool = True,\n use_attr_as_opacity=None,\n positive_only=None\n):\n\"\"\"\n Configures the default parameters for the `__call__` method (these can \n be overridden by passing in values to `__call__`).\n\n Parameters:\n model:\n The wrapped model whose channel we're visualizing.\n\n layer:\n The identifier (either index or name) of the layer in which the \n channel we're visualizing resides.\n\n channel:\n Index of the channel (for convolutional layers) or internal \n neuron (for fully-connected layers) that we'd like to visualize.\n\n channel_axis:\n If different from the channel axis specified by the backend, the\n supplied `channel_axis` will be used if operating on a \n convolutional layer with 4-D image format.\n\n agg_fn:\n Function with which to aggregate the remaining dimensions \n (except the batch dimension) in order to get a single scalar \n value for each channel; If `None`, a sum over each neuron in the\n channel will be taken. This argument is not used when the \n channels are scalars, e.g., for dense layers.\n\n doi:\n The distribution of interest to use when computing the input\n attributions towards the specified channel. If `None`, \n `PointDoI` will be used.\n\n blur:\n Gives the radius of a Gaussian blur to be applied to the \n attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels.\n\n threshold:\n Value in the range [0, 1]. Attribution values at or below the \n percentile given by `threshold` (after normalization, blurring,\n etc.) will be masked.\n\n masked_opacity: \n Value in the range [0, 1] specifying the opacity for the parts\n of the image that are masked.\n\n combine_channels:\n If `True`, the attributions will be averaged across the channel\n dimension, resulting in a 1-channel attribution map.\n\n use_attr_as_opacity:\n If `True`, instead of using `threshold` and `masked_opacity`,\n the opacity of each pixel is given by the 0-1-normalized \n attribution value.\n\n positive_only:\n If `True`, only pixels with positive attribution will be \n unmasked (or given nonzero opacity when `use_attr_as_opacity` is\n true).\n \"\"\"\n B = get_backend()\n if (B is not None and (channel_axis is None or channel_axis < 0)):\n channel_axis = B.channel_axis\n elif (channel_axis is None or channel_axis < 0):\n channel_axis = 1\n\n self.mask_visualizer = MaskVisualizer(\n blur, threshold, masked_opacity, combine_channels,\n use_attr_as_opacity, positive_only\n )\n\n self.infl_input = InternalInfluence(\n model, (InputCut(), Cut(layer)),\n InternalChannelQoI(channel, channel_axis, agg_fn),\n PointDoi() if doi is None else doi\n )\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.HTML","title":"
HTML","text":"
Bases: Output
HTML visualization output format.
Source code in
trulens_explain/trulens/visualizations.py class HTML(Output):\n\"\"\"HTML visualization output format.\"\"\"\n\n def __init__(self):\n try:\n self.m_html = importlib.import_module(\"html\")\n except:\n raise ImportError(\n \"HTML output requires html python module. Try 'pip install html'.\"\n )\n\n def blank(self):\n return \"\"\n\n def space(self):\n return \" \"\n\n def escape(self, s):\n return self.m_html.escape(s)\n\n def linebreak(self):\n return \"<br/>\"\n\n def line(self, s):\n return f\"<span style='padding: 2px; margin: 2px; background: gray; border-radius: 4px;'>{s}</span>\"\n\n def magnitude_colored(self, s, mag):\n red = 0.0\n green = 0.0\n if mag > 0:\n green = 1.0 # 0.5 + mag * 0.5\n red = 1.0 - mag * 0.5\n else:\n red = 1.0\n green = 1.0 + mag * 0.5\n #red = 0.5 - mag * 0.5\n\n blue = min(red, green)\n # blue = 1.0 - max(red, green)\n\n return f\"<span title='{mag:0.3f}' style='margin: 1px; padding: 1px; border-radius: 4px; background: black; color: rgb({red*255}, {green*255}, {blue*255});'>{s}</span>\"\n\n def append(self, *pieces):\n return ''.join(pieces)\n\n def render(self, s):\n return s\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.HeatmapVisualizer","title":"
HeatmapVisualizer","text":"
Bases: Visualizer
Visualizes attributions by overlaying an attribution heatmap over the original image, similar to how GradCAM visualizes attributions.
Source code in
trulens_explain/trulens/visualizations.py class HeatmapVisualizer(Visualizer):\n\"\"\"\n Visualizes attributions by overlaying an attribution heatmap over the\n original image, similar to how GradCAM visualizes attributions.\n \"\"\"\n\n def __init__(\n self,\n overlay_opacity=0.5,\n normalization_type=None,\n blur=10.,\n cmap='jet'\n ):\n\"\"\"\n Configures the default parameters for the `__call__` method (these can \n be overridden by passing in values to `__call__`).\n\n Parameters:\n overlay_opacity: float\n Value in the range [0, 1] specifying the opacity for the heatmap\n overlay.\n\n normalization_type:\n Specifies one of the following configurations for normalizing\n the attributions (each item is normalized separately):\n\n - `'unsigned_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the attributions by the maximum absolute \n attribution value.\n - `'unsigned_max_positive_centered'`: same as above, but scales\n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5. \n - `'magnitude_max'`: takes the absolute value of the \n attributions, then normalizes the attributions to the range \n [0, 1] by dividing by the maximum absolute attribution value.\n - `'magnitude_sum'`: takes the absolute value of the \n attributions, then scales them such that they sum to 1. If \n this option is used, each channel is normalized separately, \n such that each channel sums to 1.\n - `'signed_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the positive values by the maximum \n positive attribution value and the negative values by the \n minimum negative attribution value.\n - `'signed_max_positive_centered'`: same as above, but scales \n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5.\n - `'signed_sum'`: scales the positive attributions such that \n they sum to 1 and the negative attributions such that they\n scale to -1. If this option is used, each channel is \n normalized separately.\n - `'01'`: normalizes the attributions to the range [0, 1] by \n subtracting the minimum attribution value then dividing by the\n maximum attribution value.\n - `'unnormalized'`: leaves the attributions unaffected.\n\n If `None`, either `'unsigned_max'` (for single-channel data) or \n `'unsigned_max_positive_centered'` (for multi-channel data) is\n used.\n\n blur:\n Gives the radius of a Gaussian blur to be applied to the \n attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels.\n\n cmap: matplotlib.colors.Colormap | str, optional\n Colormap or name of a Colormap to use for the visualization. If \n `None`, the colormap will be chosen based on the normalization \n type. This argument is only used for single-channel data\n (including when `combine_channels` is True).\n \"\"\"\n\n super().__init__(\n combine_channels=True,\n normalization_type=normalization_type,\n blur=blur,\n cmap=cmap\n )\n\n self.default_overlay_opacity = overlay_opacity\n\n def __call__(\n self,\n attributions,\n x,\n output_file=None,\n imshow=True,\n fig=None,\n return_tiled=False,\n overlay_opacity=None,\n normalization_type=None,\n blur=None,\n cmap=None\n ) -> np.ndarray:\n\"\"\"\n Visualizes the given attributions by overlaying an attribution heatmap \n over the given image.\n\n Parameters:\n attributions:\n A `np.ndarray` containing the attributions to be visualized.\n\n x:\n A `np.ndarray` of items in the same shape as `attributions`\n corresponding to the records explained by the given \n attributions. The visualization will be superimposed onto the\n corresponding set of records.\n\n output_file:\n File name to save the visualization image to. If `None`, no\n image will be saved, but the figure can still be displayed.\n\n imshow:\n If true, a the visualization will be displayed. Otherwise the\n figure will not be displayed, but the figure can still be saved.\n\n fig:\n The `pyplot` figure to display the visualization in. If `None`,\n a new figure will be created.\n\n return_tiled:\n If true, the returned array will be in the same shape as the\n visualization, with no batch dimension and the samples in the\n batch tiled along the width and height dimensions. If false, the\n returned array will be reshaped to match `attributions`.\n\n overlay_opacity: float\n Value in the range [0, 1] specifying the opacity for the heatmap\n overlay. If `None`, defaults to the value supplied to the \n constructor.\n\n normalization_type:\n Specifies one of the following configurations for normalizing\n the attributions (each item is normalized separately):\n\n - `'unsigned_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the attributions by the maximum absolute \n attribution value.\n - `'unsigned_max_positive_centered'`: same as above, but scales\n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5. \n - `'magnitude_max'`: takes the absolute value of the \n attributions, then normalizes the attributions to the range \n [0, 1] by dividing by the maximum absolute attribution value.\n - `'magnitude_sum'`: takes the absolute value of the \n attributions, then scales them such that they sum to 1. If \n this option is used, each channel is normalized separately, \n such that each channel sums to 1.\n - `'signed_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the positive values by the maximum \n positive attribution value and the negative values by the \n minimum negative attribution value.\n - `'signed_max_positive_centered'`: same as above, but scales \n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5.\n - `'signed_sum'`: scales the positive attributions such that \n they sum to 1 and the negative attributions such that they\n scale to -1. If this option is used, each channel is \n normalized separately.\n - `'01'`: normalizes the attributions to the range [0, 1] by \n subtracting the minimum attribution value then dividing by the\n maximum attribution value.\n - `'unnormalized'`: leaves the attributions unaffected.\n\n If `None`, defaults to the value supplied to the constructor.\n\n blur:\n Gives the radius of a Gaussian blur to be applied to the \n attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels. If\n `None`, defaults to the value supplied to the constructor.\n\n cmap: matplotlib.colors.Colormap | str, optional\n Colormap or name of a Colormap to use for the visualization. If\n `None`, defaults to the value supplied to the constructor.\n\n Returns:\n A `np.ndarray` array of the numerical representation of the\n attributions as modified for the visualization. This includes \n normalization, blurring, etc.\n \"\"\"\n _, normalization_type, blur, cmap = self._check_args(\n attributions, None, normalization_type, blur, cmap\n )\n\n # Combine the channels.\n attributions = attributions.mean(\n axis=get_backend().channel_axis, keepdims=True\n )\n\n # Blur the attributions so the explanation is smoother.\n if blur:\n attributions = self._blur(attributions, blur)\n\n # Normalize the attributions.\n attributions = self._normalize(attributions, normalization_type)\n\n tiled_attributions = self.tiler.tile(attributions)\n\n # Normalize the pixels to be in the range [0, 1].\n x = self._normalize(x, '01')\n tiled_x = self.tiler.tile(x)\n\n if cmap is None:\n cmap = self.default_cmap\n\n if overlay_opacity is None:\n overlay_opacity = self.default_overlay_opacity\n\n # Display the figure:\n _fig = plt.figure() if fig is None else fig\n\n plt.axis('off')\n plt.imshow(tiled_x)\n plt.imshow(tiled_attributions, alpha=overlay_opacity, cmap=cmap)\n\n if output_file:\n plt.savefig(output_file, bbox_inches=0)\n\n if imshow:\n plt.show()\n\n elif fig is None:\n plt.close(_fig)\n\n return tiled_attributions if return_tiled else attributions\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.HeatmapVisualizer.__call__","title":"
__call__(attributions, x, output_file=None, imshow=True, fig=None, return_tiled=False, overlay_opacity=None, normalization_type=None, blur=None, cmap=None)","text":"
Visualizes the given attributions by overlaying an attribution heatmap over the given image.
Parameters:
Name Type Description Default
attributions A np.ndarray containing the attributions to be visualized.
required
x A np.ndarray of items in the same shape as attributions corresponding to the records explained by the given attributions. The visualization will be superimposed onto the corresponding set of records.
required
output_file File name to save the visualization image to. If None, no image will be saved, but the figure can still be displayed.
None imshow If true, a the visualization will be displayed. Otherwise the figure will not be displayed, but the figure can still be saved.
True fig The pyplot figure to display the visualization in. If None, a new figure will be created.
None return_tiled If true, the returned array will be in the same shape as the visualization, with no batch dimension and the samples in the batch tiled along the width and height dimensions. If false, the returned array will be reshaped to match attributions.
False overlay_opacity float Value in the range [0, 1] specifying the opacity for the heatmap overlay. If None, defaults to the value supplied to the constructor.
None normalization_type Specifies one of the following configurations for normalizing the attributions (each item is normalized separately):
'unsigned_max': normalizes the attributions to the range [-1, 1] by dividing the attributions by the maximum absolute attribution value.'unsigned_max_positive_centered': same as above, but scales the values to the range [0, 1], with negative scores less than 0.5 and positive scores greater than 0.5. 'magnitude_max': takes the absolute value of the attributions, then normalizes the attributions to the range [0, 1] by dividing by the maximum absolute attribution value.'magnitude_sum': takes the absolute value of the attributions, then scales them such that they sum to 1. If this option is used, each channel is normalized separately, such that each channel sums to 1.'signed_max': normalizes the attributions to the range [-1, 1] by dividing the positive values by the maximum positive attribution value and the negative values by the minimum negative attribution value.'signed_max_positive_centered': same as above, but scales the values to the range [0, 1], with negative scores less than 0.5 and positive scores greater than 0.5.'signed_sum': scales the positive attributions such that they sum to 1 and the negative attributions such that they scale to -1. If this option is used, each channel is normalized separately.'01': normalizes the attributions to the range [0, 1] by subtracting the minimum attribution value then dividing by the maximum attribution value.'unnormalized': leaves the attributions unaffected.
If None, defaults to the value supplied to the constructor.
None blur Gives the radius of a Gaussian blur to be applied to the attributions before visualizing. This can be used to help focus on salient regions rather than specific salient pixels. If None, defaults to the value supplied to the constructor.
None cmap matplotlib.colors.Colormap | str, optional Colormap or name of a Colormap to use for the visualization. If None, defaults to the value supplied to the constructor.
None Returns:
Type Description
np.ndarray A np.ndarray array of the numerical representation of the
np.ndarray attributions as modified for the visualization. This includes
np.ndarray normalization, blurring, etc.
Source code in
trulens_explain/trulens/visualizations.py def __call__(\n self,\n attributions,\n x,\n output_file=None,\n imshow=True,\n fig=None,\n return_tiled=False,\n overlay_opacity=None,\n normalization_type=None,\n blur=None,\n cmap=None\n) -> np.ndarray:\n\"\"\"\n Visualizes the given attributions by overlaying an attribution heatmap \n over the given image.\n\n Parameters:\n attributions:\n A `np.ndarray` containing the attributions to be visualized.\n\n x:\n A `np.ndarray` of items in the same shape as `attributions`\n corresponding to the records explained by the given \n attributions. The visualization will be superimposed onto the\n corresponding set of records.\n\n output_file:\n File name to save the visualization image to. If `None`, no\n image will be saved, but the figure can still be displayed.\n\n imshow:\n If true, a the visualization will be displayed. Otherwise the\n figure will not be displayed, but the figure can still be saved.\n\n fig:\n The `pyplot` figure to display the visualization in. If `None`,\n a new figure will be created.\n\n return_tiled:\n If true, the returned array will be in the same shape as the\n visualization, with no batch dimension and the samples in the\n batch tiled along the width and height dimensions. If false, the\n returned array will be reshaped to match `attributions`.\n\n overlay_opacity: float\n Value in the range [0, 1] specifying the opacity for the heatmap\n overlay. If `None`, defaults to the value supplied to the \n constructor.\n\n normalization_type:\n Specifies one of the following configurations for normalizing\n the attributions (each item is normalized separately):\n\n - `'unsigned_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the attributions by the maximum absolute \n attribution value.\n - `'unsigned_max_positive_centered'`: same as above, but scales\n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5. \n - `'magnitude_max'`: takes the absolute value of the \n attributions, then normalizes the attributions to the range \n [0, 1] by dividing by the maximum absolute attribution value.\n - `'magnitude_sum'`: takes the absolute value of the \n attributions, then scales them such that they sum to 1. If \n this option is used, each channel is normalized separately, \n such that each channel sums to 1.\n - `'signed_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the positive values by the maximum \n positive attribution value and the negative values by the \n minimum negative attribution value.\n - `'signed_max_positive_centered'`: same as above, but scales \n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5.\n - `'signed_sum'`: scales the positive attributions such that \n they sum to 1 and the negative attributions such that they\n scale to -1. If this option is used, each channel is \n normalized separately.\n - `'01'`: normalizes the attributions to the range [0, 1] by \n subtracting the minimum attribution value then dividing by the\n maximum attribution value.\n - `'unnormalized'`: leaves the attributions unaffected.\n\n If `None`, defaults to the value supplied to the constructor.\n\n blur:\n Gives the radius of a Gaussian blur to be applied to the \n attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels. If\n `None`, defaults to the value supplied to the constructor.\n\n cmap: matplotlib.colors.Colormap | str, optional\n Colormap or name of a Colormap to use for the visualization. If\n `None`, defaults to the value supplied to the constructor.\n\n Returns:\n A `np.ndarray` array of the numerical representation of the\n attributions as modified for the visualization. This includes \n normalization, blurring, etc.\n \"\"\"\n _, normalization_type, blur, cmap = self._check_args(\n attributions, None, normalization_type, blur, cmap\n )\n\n # Combine the channels.\n attributions = attributions.mean(\n axis=get_backend().channel_axis, keepdims=True\n )\n\n # Blur the attributions so the explanation is smoother.\n if blur:\n attributions = self._blur(attributions, blur)\n\n # Normalize the attributions.\n attributions = self._normalize(attributions, normalization_type)\n\n tiled_attributions = self.tiler.tile(attributions)\n\n # Normalize the pixels to be in the range [0, 1].\n x = self._normalize(x, '01')\n tiled_x = self.tiler.tile(x)\n\n if cmap is None:\n cmap = self.default_cmap\n\n if overlay_opacity is None:\n overlay_opacity = self.default_overlay_opacity\n\n # Display the figure:\n _fig = plt.figure() if fig is None else fig\n\n plt.axis('off')\n plt.imshow(tiled_x)\n plt.imshow(tiled_attributions, alpha=overlay_opacity, cmap=cmap)\n\n if output_file:\n plt.savefig(output_file, bbox_inches=0)\n\n if imshow:\n plt.show()\n\n elif fig is None:\n plt.close(_fig)\n\n return tiled_attributions if return_tiled else attributions\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.HeatmapVisualizer.__init__","title":"
__init__(overlay_opacity=0.5, normalization_type=None, blur=10.0, cmap='jet')","text":"
Configures the default parameters for the __call__ method (these can be overridden by passing in values to __call__).
Parameters:
Name Type Description Default
overlay_opacity float Value in the range [0, 1] specifying the opacity for the heatmap overlay.
0.5 normalization_type Specifies one of the following configurations for normalizing the attributions (each item is normalized separately):
'unsigned_max': normalizes the attributions to the range [-1, 1] by dividing the attributions by the maximum absolute attribution value.'unsigned_max_positive_centered': same as above, but scales the values to the range [0, 1], with negative scores less than 0.5 and positive scores greater than 0.5. 'magnitude_max': takes the absolute value of the attributions, then normalizes the attributions to the range [0, 1] by dividing by the maximum absolute attribution value.'magnitude_sum': takes the absolute value of the attributions, then scales them such that they sum to 1. If this option is used, each channel is normalized separately, such that each channel sums to 1.'signed_max': normalizes the attributions to the range [-1, 1] by dividing the positive values by the maximum positive attribution value and the negative values by the minimum negative attribution value.'signed_max_positive_centered': same as above, but scales the values to the range [0, 1], with negative scores less than 0.5 and positive scores greater than 0.5.'signed_sum': scales the positive attributions such that they sum to 1 and the negative attributions such that they scale to -1. If this option is used, each channel is normalized separately.'01': normalizes the attributions to the range [0, 1] by subtracting the minimum attribution value then dividing by the maximum attribution value.'unnormalized': leaves the attributions unaffected.
If None, either 'unsigned_max' (for single-channel data) or 'unsigned_max_positive_centered' (for multi-channel data) is used.
None blur Gives the radius of a Gaussian blur to be applied to the attributions before visualizing. This can be used to help focus on salient regions rather than specific salient pixels.
10.0 cmap matplotlib.colors.Colormap | str, optional Colormap or name of a Colormap to use for the visualization. If None, the colormap will be chosen based on the normalization type. This argument is only used for single-channel data (including when combine_channels is True).
'jet' Source code in
trulens_explain/trulens/visualizations.py def __init__(\n self,\n overlay_opacity=0.5,\n normalization_type=None,\n blur=10.,\n cmap='jet'\n):\n\"\"\"\n Configures the default parameters for the `__call__` method (these can \n be overridden by passing in values to `__call__`).\n\n Parameters:\n overlay_opacity: float\n Value in the range [0, 1] specifying the opacity for the heatmap\n overlay.\n\n normalization_type:\n Specifies one of the following configurations for normalizing\n the attributions (each item is normalized separately):\n\n - `'unsigned_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the attributions by the maximum absolute \n attribution value.\n - `'unsigned_max_positive_centered'`: same as above, but scales\n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5. \n - `'magnitude_max'`: takes the absolute value of the \n attributions, then normalizes the attributions to the range \n [0, 1] by dividing by the maximum absolute attribution value.\n - `'magnitude_sum'`: takes the absolute value of the \n attributions, then scales them such that they sum to 1. If \n this option is used, each channel is normalized separately, \n such that each channel sums to 1.\n - `'signed_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the positive values by the maximum \n positive attribution value and the negative values by the \n minimum negative attribution value.\n - `'signed_max_positive_centered'`: same as above, but scales \n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5.\n - `'signed_sum'`: scales the positive attributions such that \n they sum to 1 and the negative attributions such that they\n scale to -1. If this option is used, each channel is \n normalized separately.\n - `'01'`: normalizes the attributions to the range [0, 1] by \n subtracting the minimum attribution value then dividing by the\n maximum attribution value.\n - `'unnormalized'`: leaves the attributions unaffected.\n\n If `None`, either `'unsigned_max'` (for single-channel data) or \n `'unsigned_max_positive_centered'` (for multi-channel data) is\n used.\n\n blur:\n Gives the radius of a Gaussian blur to be applied to the \n attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels.\n\n cmap: matplotlib.colors.Colormap | str, optional\n Colormap or name of a Colormap to use for the visualization. If \n `None`, the colormap will be chosen based on the normalization \n type. This argument is only used for single-channel data\n (including when `combine_channels` is True).\n \"\"\"\n\n super().__init__(\n combine_channels=True,\n normalization_type=normalization_type,\n blur=blur,\n cmap=cmap\n )\n\n self.default_overlay_opacity = overlay_opacity\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.IPython","title":"
IPython","text":"
Bases: HTML
Interactive python visualization output format.
Source code in
trulens_explain/trulens/visualizations.py class IPython(HTML):\n\"\"\"Interactive python visualization output format.\"\"\"\n\n def __init__(self):\n super(IPython, self).__init__()\n try:\n self.m_ipy = importlib.import_module(\"IPython\")\n except:\n raise ImportError(\n \"Jupyter output requires IPython python module. Try 'pip install ipykernel'.\"\n )\n\n def render(self, s: str):\n html = HTML.render(self, s)\n return self.m_ipy.display.HTML(html)\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.MaskVisualizer","title":"
MaskVisualizer","text":"
Bases: object
Visualizes attributions by masking the original image to highlight the regions with influence above a given threshold percentile. Intended particularly for use with input-attributions.
Source code in
trulens_explain/trulens/visualizations.py class MaskVisualizer(object):\n\"\"\"\n Visualizes attributions by masking the original image to highlight the\n regions with influence above a given threshold percentile. Intended \n particularly for use with input-attributions.\n \"\"\"\n\n def __init__(\n self,\n blur=5.,\n threshold=0.5,\n masked_opacity=0.2,\n combine_channels=True,\n use_attr_as_opacity=False,\n positive_only=True\n ):\n\"\"\"\n Configures the default parameters for the `__call__` method (these can \n be overridden by passing in values to `__call__`).\n\n Parameters:\n blur:\n Gives the radius of a Gaussian blur to be applied to the \n attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels.\n\n threshold:\n Value in the range [0, 1]. Attribution values at or below the \n percentile given by `threshold` (after normalization, blurring,\n etc.) will be masked.\n\n masked_opacity: \n Value in the range [0, 1] specifying the opacity for the parts\n of the image that are masked.\n\n combine_channels:\n If `True`, the attributions will be averaged across the channel\n dimension, resulting in a 1-channel attribution map.\n\n use_attr_as_opacity:\n If `True`, instead of using `threshold` and `masked_opacity`,\n the opacity of each pixel is given by the 0-1-normalized \n attribution value.\n\n positive_only:\n If `True`, only pixels with positive attribution will be \n unmasked (or given nonzero opacity when `use_attr_as_opacity` is\n true).\n \"\"\"\n\n self.default_blur = blur\n self.default_thresh = threshold\n self.default_masked_opacity = masked_opacity\n self.default_combine_channels = combine_channels\n\n # TODO(klas): in the future we can allow configuring of tiling settings\n # by allowing the user to specify the tiler.\n self.tiler = Tiler()\n\n def __call__(\n self,\n attributions,\n x,\n output_file=None,\n imshow=True,\n fig=None,\n return_tiled=True,\n blur=None,\n threshold=None,\n masked_opacity=None,\n combine_channels=None,\n use_attr_as_opacity=None,\n positive_only=None\n ):\n channel_axis = get_backend().channel_axis\n if attributions.shape != x.shape:\n raise ValueError(\n 'Shape of `attributions` {} must match shape of `x` {}'.format(\n attributions.shape, x.shape\n )\n )\n\n if blur is None:\n blur = self.default_blur\n\n if threshold is None:\n threshold = self.default_thresh\n\n if masked_opacity is None:\n masked_opacity = self.default_masked_opacity\n\n if combine_channels is None:\n combine_channels = self.default_combine_channels\n\n if len(attributions.shape) != 4:\n raise ValueError(\n '`MaskVisualizer` is inteded for 4-D image-format data. Given '\n 'input with dimension {}'.format(len(attributions.shape))\n )\n\n if combine_channels is None:\n combine_channels = self.default_combine_channels\n\n if combine_channels:\n attributions = attributions.mean(axis=channel_axis, keepdims=True)\n\n if x.shape[channel_axis] not in (1, 3, 4):\n raise ValueError(\n 'To visualize, attributions must have either 1, 3, or 4 color '\n 'channels, but Visualizer got {} channels.\\n'\n 'If you are visualizing an internal layer, consider setting '\n '`combine_channels` to True'.format(\n attributions.shape[channel_axis]\n )\n )\n\n # Blur the attributions so the explanation is smoother.\n if blur is not None:\n attributions = [gaussian_filter(a, blur) for a in attributions]\n\n # If `positive_only` clip attributions.\n if positive_only:\n attributions = np.maximum(attributions, 0)\n\n # Normalize the attributions to be in the range [0, 1].\n attributions = [a - a.min() for a in attributions]\n attributions = [\n 0. * a if a.max() == 0. else a / a.max() for a in attributions\n ]\n\n # Normalize the pixels to be in the range [0, 1]\n x = [xc - xc.min() for xc in x]\n x = np.array([0. * xc if xc.max() == 0. else xc / xc.max() for xc in x])\n\n # Threshold the attributions to create a mask.\n if threshold is not None:\n percentiles = [\n np.percentile(a, 100 * threshold) for a in attributions\n ]\n masks = np.array(\n [\n np.maximum(a > p, masked_opacity)\n for a, p in zip(attributions, percentiles)\n ]\n )\n\n else:\n masks = np.array(attributions)\n\n # Use the mask on the original image to visualize the explanation.\n attributions = masks * x\n tiled_attributions = self.tiler.tile(attributions)\n\n if imshow:\n plt.axis('off')\n plt.imshow(tiled_attributions)\n\n if output_file:\n plt.savefig(output_file, bbox_inches=0)\n\n return tiled_attributions if return_tiled else attributions\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.MaskVisualizer.__init__","title":"
__init__(blur=5.0, threshold=0.5, masked_opacity=0.2, combine_channels=True, use_attr_as_opacity=False, positive_only=True)","text":"
Configures the default parameters for the __call__ method (these can be overridden by passing in values to __call__).
Parameters:
Name Type Description Default
blur Gives the radius of a Gaussian blur to be applied to the attributions before visualizing. This can be used to help focus on salient regions rather than specific salient pixels.
5.0 threshold Value in the range [0, 1]. Attribution values at or below the percentile given by threshold (after normalization, blurring, etc.) will be masked.
0.5 masked_opacity Value in the range [0, 1] specifying the opacity for the parts of the image that are masked.
0.2 combine_channels If True, the attributions will be averaged across the channel dimension, resulting in a 1-channel attribution map.
True use_attr_as_opacity If True, instead of using threshold and masked_opacity, the opacity of each pixel is given by the 0-1-normalized attribution value.
False positive_only If True, only pixels with positive attribution will be unmasked (or given nonzero opacity when use_attr_as_opacity is true).
True Source code in
trulens_explain/trulens/visualizations.py def __init__(\n self,\n blur=5.,\n threshold=0.5,\n masked_opacity=0.2,\n combine_channels=True,\n use_attr_as_opacity=False,\n positive_only=True\n):\n\"\"\"\n Configures the default parameters for the `__call__` method (these can \n be overridden by passing in values to `__call__`).\n\n Parameters:\n blur:\n Gives the radius of a Gaussian blur to be applied to the \n attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels.\n\n threshold:\n Value in the range [0, 1]. Attribution values at or below the \n percentile given by `threshold` (after normalization, blurring,\n etc.) will be masked.\n\n masked_opacity: \n Value in the range [0, 1] specifying the opacity for the parts\n of the image that are masked.\n\n combine_channels:\n If `True`, the attributions will be averaged across the channel\n dimension, resulting in a 1-channel attribution map.\n\n use_attr_as_opacity:\n If `True`, instead of using `threshold` and `masked_opacity`,\n the opacity of each pixel is given by the 0-1-normalized \n attribution value.\n\n positive_only:\n If `True`, only pixels with positive attribution will be \n unmasked (or given nonzero opacity when `use_attr_as_opacity` is\n true).\n \"\"\"\n\n self.default_blur = blur\n self.default_thresh = threshold\n self.default_masked_opacity = masked_opacity\n self.default_combine_channels = combine_channels\n\n # TODO(klas): in the future we can allow configuring of tiling settings\n # by allowing the user to specify the tiler.\n self.tiler = Tiler()\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.NLP","title":"
NLP","text":"
Bases: object
NLP Visualization tools.
Source code in
trulens_explain/trulens/visualizations.py class NLP(object):\n\"\"\"NLP Visualization tools.\"\"\"\n\n # Batches of text inputs not yet tokenized.\n TextBatch = TypeVar(\"TextBatch\")\n\n # Inputs that are directly accepted by wrapped models, tokenized.\n # TODO(piotrm): Reuse other typevars/aliases from elsewhere.\n ModelInput = TypeVar(\"ModelInput\")\n\n # Outputs produced by wrapped models.\n # TODO(piotrm): Reuse other typevars/aliases from elsewhere.\n ModelOutput = TypeVar(\"ModelOutput\")\n\n def __init__(\n self,\n wrapper: ModelWrapper,\n output: Optional[Output] = None,\n labels: Optional[Iterable[str]] = None,\n tokenize: Optional[Callable[[TextBatch], ModelInputs]] = None,\n decode: Optional[Callable[[Tensor], str]] = None,\n input_accessor: Optional[Callable[[ModelInputs],\n Iterable[Tensor]]] = None,\n output_accessor: Optional[Callable[[ModelOutput],\n Iterable[Tensor]]] = None,\n attr_aggregate: Optional[Callable[[Tensor], Tensor]] = None,\n hidden_tokens: Optional[Set[int]] = set()\n ):\n\"\"\"Initializate NLP visualization tools for a given environment.\n\n Parameters:\n wrapper: ModelWrapper\n The wrapped model whose channel we're visualizing.\n\n output: Output, optional\n Visualization output format. Defaults to PlainText unless\n ipython is detected and in which case defaults to IPython\n format.\n\n labels: Iterable[str], optional\n Names of prediction classes for classification models.\n\n tokenize: Callable[[TextBatch], ModelInput], optional\n Method to tokenize an instance.\n\n decode: Callable[[Tensor], str], optional\n Method to invert/decode the tokenization.\n\n input_accessor: Callable[[ModelInputs], Iterable[Tensor]], optional\n Method to extract input/token ids from model inputs (tokenize\n output) if needed.\n\n output_accessor: Callable[[ModelOutput], Iterable[Tensor]], optional\n Method to extract outout logits from output structures if\n needed.\n\n attr_aggregate: Callable[[Tensor], Tensor], optional\n Method to aggregate attribution for embedding into a single\n value. Defaults to sum.\n\n hidden_tokens: Set[int], optional\n For token-based visualizations, which tokens to hide.\n \"\"\"\n if output is None:\n try:\n # check if running in interactive python (jupyer, colab, etc) to\n # use appropriate output format\n get_ipython()\n output = IPython()\n\n except NameError:\n output = PlainText()\n tru_logger(\n \"WARNING: could not guess preferred visualization output format, using PlainText\"\n )\n\n # TODO: automatic inference of various parameters for common repositories like huggingface, tfhub.\n\n self.output = output\n self.labels = labels\n self.tokenize = tokenize\n self.decode = decode\n self.wrapper = wrapper\n\n self.input_accessor = input_accessor # could be inferred\n self.output_accessor = output_accessor # could be inferred\n\n B = get_backend()\n\n if attr_aggregate is None:\n attr_aggregate = B.sum\n\n self.attr_aggregate = attr_aggregate\n\n self.hidden_tokens = hidden_tokens\n\n def token_attribution(self, texts: Iterable[str], attr: AttributionMethod):\n\"\"\"Visualize a token-based input attribution on given `texts` inputs via the attribution method `attr`.\n\n Parameters:\n texts: Iterable[str]\n The input texts to visualize.\n\n attr: AttributionMethod\n The attribution method to generate the token importances with.\n\n Returns: Any\n The visualization in the format specified by this class's `output` parameter.\n \"\"\"\n\n B = get_backend()\n\n if self.tokenize is None:\n return ValueError(\"tokenize not provided to NLP visualizer.\")\n\n inputs = self.tokenize(texts)\n\n outputs = inputs.call_on(self.wrapper._model)\n attrs = inputs.call_on(attr.attributions)\n\n content = self.output.blank()\n\n input_ids = inputs\n if self.input_accessor is not None:\n input_ids = self.input_accessor(inputs)\n\n if (not isinstance(input_ids, Iterable)) or isinstance(input_ids, dict):\n raise ValueError(\n f\"Inputs ({input_ids.__class__.__name__}) need to be iterable over instances. You might need to set input_accessor.\"\n )\n\n output_logits = outputs\n if self.output_accessor is not None:\n output_logits = self.output_accessor(outputs)\n\n if (not isinstance(output_logits, Iterable)) or isinstance(\n output_logits, dict):\n raise ValueError(\n f\"Outputs ({output_logits.__class__.__name__}) need to be iterable over instances. You might need to set output_accessor.\"\n )\n\n for i, (sentence_word_id, attr,\n logits) in enumerate(zip(input_ids, attrs, output_logits)):\n\n logits = logits.to('cpu').detach().numpy()\n pred = logits.argmax()\n\n if self.labels is not None:\n pred_name = self.labels[pred]\n else:\n pred_name = str(pred)\n\n sent = self.output.append(\n self.output.escape(pred_name), \":\", self.output.space()\n )\n\n for word_id, attr in zip(sentence_word_id, attr):\n word_id = int(B.as_array(word_id))\n\n if word_id in self.hidden_tokens:\n continue\n\n if self.decode is not None:\n word = self.decode(word_id)\n else:\n word = str(word_id)\n\n mag = self.attr_aggregate(attr)\n\n if word[0] == ' ':\n word = word[1:]\n sent = self.output.append(sent, self.output.space())\n\n sent = self.output.append(\n sent,\n self.output.magnitude_colored(\n self.output.escape(word), mag\n )\n )\n\n content = self.output.append(\n content, self.output.line(sent), self.output.linebreak(),\n self.output.linebreak()\n )\n\n return self.output.render(content)\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.NLP.__init__","title":"
__init__(wrapper, output=None, labels=None, tokenize=None, decode=None, input_accessor=None, output_accessor=None, attr_aggregate=None, hidden_tokens=set())","text":"
Initializate NLP visualization tools for a given environment.
Parameters:
Name Type Description Default
wrapper ModelWrapper ModelWrapper The wrapped model whose channel we're visualizing.
required
output Optional[Output] Output, optional Visualization output format. Defaults to PlainText unless ipython is detected and in which case defaults to IPython format.
None labels Optional[Iterable[str]] Iterable[str], optional Names of prediction classes for classification models.
None tokenize Optional[Callable[[TextBatch], ModelInputs]] Callable[[TextBatch], ModelInput], optional Method to tokenize an instance.
None decode Optional[Callable[[Tensor], str]] Callable[[Tensor], str], optional Method to invert/decode the tokenization.
None input_accessor Optional[Callable[[ModelInputs], Iterable[Tensor]]] Callable[[ModelInputs], Iterable[Tensor]], optional Method to extract input/token ids from model inputs (tokenize output) if needed.
None output_accessor Optional[Callable[[ModelOutput], Iterable[Tensor]]] Callable[[ModelOutput], Iterable[Tensor]], optional Method to extract outout logits from output structures if needed.
None attr_aggregate Optional[Callable[[Tensor], Tensor]] Callable[[Tensor], Tensor], optional Method to aggregate attribution for embedding into a single value. Defaults to sum.
None hidden_tokens Optional[Set[int]] Set[int], optional For token-based visualizations, which tokens to hide.
set() Source code in
trulens_explain/trulens/visualizations.py def __init__(\n self,\n wrapper: ModelWrapper,\n output: Optional[Output] = None,\n labels: Optional[Iterable[str]] = None,\n tokenize: Optional[Callable[[TextBatch], ModelInputs]] = None,\n decode: Optional[Callable[[Tensor], str]] = None,\n input_accessor: Optional[Callable[[ModelInputs],\n Iterable[Tensor]]] = None,\n output_accessor: Optional[Callable[[ModelOutput],\n Iterable[Tensor]]] = None,\n attr_aggregate: Optional[Callable[[Tensor], Tensor]] = None,\n hidden_tokens: Optional[Set[int]] = set()\n):\n\"\"\"Initializate NLP visualization tools for a given environment.\n\n Parameters:\n wrapper: ModelWrapper\n The wrapped model whose channel we're visualizing.\n\n output: Output, optional\n Visualization output format. Defaults to PlainText unless\n ipython is detected and in which case defaults to IPython\n format.\n\n labels: Iterable[str], optional\n Names of prediction classes for classification models.\n\n tokenize: Callable[[TextBatch], ModelInput], optional\n Method to tokenize an instance.\n\n decode: Callable[[Tensor], str], optional\n Method to invert/decode the tokenization.\n\n input_accessor: Callable[[ModelInputs], Iterable[Tensor]], optional\n Method to extract input/token ids from model inputs (tokenize\n output) if needed.\n\n output_accessor: Callable[[ModelOutput], Iterable[Tensor]], optional\n Method to extract outout logits from output structures if\n needed.\n\n attr_aggregate: Callable[[Tensor], Tensor], optional\n Method to aggregate attribution for embedding into a single\n value. Defaults to sum.\n\n hidden_tokens: Set[int], optional\n For token-based visualizations, which tokens to hide.\n \"\"\"\n if output is None:\n try:\n # check if running in interactive python (jupyer, colab, etc) to\n # use appropriate output format\n get_ipython()\n output = IPython()\n\n except NameError:\n output = PlainText()\n tru_logger(\n \"WARNING: could not guess preferred visualization output format, using PlainText\"\n )\n\n # TODO: automatic inference of various parameters for common repositories like huggingface, tfhub.\n\n self.output = output\n self.labels = labels\n self.tokenize = tokenize\n self.decode = decode\n self.wrapper = wrapper\n\n self.input_accessor = input_accessor # could be inferred\n self.output_accessor = output_accessor # could be inferred\n\n B = get_backend()\n\n if attr_aggregate is None:\n attr_aggregate = B.sum\n\n self.attr_aggregate = attr_aggregate\n\n self.hidden_tokens = hidden_tokens\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.NLP.token_attribution","title":"
token_attribution(texts, attr)","text":"
Visualize a token-based input attribution on given texts inputs via the attribution method attr.
Parameters:
Name Type Description Default
texts Iterable[str] Iterable[str] The input texts to visualize.
required
attr AttributionMethod AttributionMethod The attribution method to generate the token importances with.
required
Any
Type Description
The visualization in the format specified by this class's output parameter.
Source code in
trulens_explain/trulens/visualizations.py def token_attribution(self, texts: Iterable[str], attr: AttributionMethod):\n\"\"\"Visualize a token-based input attribution on given `texts` inputs via the attribution method `attr`.\n\n Parameters:\n texts: Iterable[str]\n The input texts to visualize.\n\n attr: AttributionMethod\n The attribution method to generate the token importances with.\n\n Returns: Any\n The visualization in the format specified by this class's `output` parameter.\n \"\"\"\n\n B = get_backend()\n\n if self.tokenize is None:\n return ValueError(\"tokenize not provided to NLP visualizer.\")\n\n inputs = self.tokenize(texts)\n\n outputs = inputs.call_on(self.wrapper._model)\n attrs = inputs.call_on(attr.attributions)\n\n content = self.output.blank()\n\n input_ids = inputs\n if self.input_accessor is not None:\n input_ids = self.input_accessor(inputs)\n\n if (not isinstance(input_ids, Iterable)) or isinstance(input_ids, dict):\n raise ValueError(\n f\"Inputs ({input_ids.__class__.__name__}) need to be iterable over instances. You might need to set input_accessor.\"\n )\n\n output_logits = outputs\n if self.output_accessor is not None:\n output_logits = self.output_accessor(outputs)\n\n if (not isinstance(output_logits, Iterable)) or isinstance(\n output_logits, dict):\n raise ValueError(\n f\"Outputs ({output_logits.__class__.__name__}) need to be iterable over instances. You might need to set output_accessor.\"\n )\n\n for i, (sentence_word_id, attr,\n logits) in enumerate(zip(input_ids, attrs, output_logits)):\n\n logits = logits.to('cpu').detach().numpy()\n pred = logits.argmax()\n\n if self.labels is not None:\n pred_name = self.labels[pred]\n else:\n pred_name = str(pred)\n\n sent = self.output.append(\n self.output.escape(pred_name), \":\", self.output.space()\n )\n\n for word_id, attr in zip(sentence_word_id, attr):\n word_id = int(B.as_array(word_id))\n\n if word_id in self.hidden_tokens:\n continue\n\n if self.decode is not None:\n word = self.decode(word_id)\n else:\n word = str(word_id)\n\n mag = self.attr_aggregate(attr)\n\n if word[0] == ' ':\n word = word[1:]\n sent = self.output.append(sent, self.output.space())\n\n sent = self.output.append(\n sent,\n self.output.magnitude_colored(\n self.output.escape(word), mag\n )\n )\n\n content = self.output.append(\n content, self.output.line(sent), self.output.linebreak(),\n self.output.linebreak()\n )\n\n return self.output.render(content)\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.Output","title":"
Output","text":"
Bases: ABC
Base class for visualization output formats.
Source code in
trulens_explain/trulens/visualizations.py class Output(ABC):\n\"\"\"Base class for visualization output formats.\"\"\"\n\n @abstractmethod\n def blank(self) -> str:\n ...\n\n @abstractmethod\n def space(self) -> str:\n ...\n\n @abstractmethod\n def escape(self, s: str) -> str:\n ...\n\n @abstractmethod\n def line(self, s: str) -> str:\n ...\n\n @abstractmethod\n def magnitude_colored(self, s: str, mag: float) -> str:\n ...\n\n @abstractmethod\n def append(self, *parts: Iterable[str]) -> str:\n ...\n\n @abstractmethod\n def render(self, s: str) -> str:\n ...\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.PlainText","title":"
PlainText","text":"
Bases: Output
Plain text visualization output format.
Source code in
trulens_explain/trulens/visualizations.py class PlainText(Output):\n\"\"\"Plain text visualization output format.\"\"\"\n\n def blank(self):\n return \"\"\n\n def space(self):\n return \" \"\n\n def escape(self, s):\n return s\n\n def line(self, s):\n return s\n\n def magnitude_colored(self, s, mag):\n return f\"{s}({mag:0.3f})\"\n\n def append(self, *parts):\n return ''.join(parts)\n\n def render(self, s):\n return s\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.Tiler","title":"
Tiler","text":"
Bases: object
Used to tile batched images or attributions.
Source code in
trulens_explain/trulens/visualizations.py class Tiler(object):\n\"\"\"\n Used to tile batched images or attributions.\n \"\"\"\n\n def tile(self, a: np.ndarray) -> np.ndarray:\n\"\"\"\n Tiles the given array into a grid that is as square as possible.\n\n Parameters:\n a:\n An array of 4D batched image data.\n\n Returns:\n A tiled array of the images from `a`. The resulting array has rank\n 3 for color images, and 2 for grayscale images (the batch dimension\n is removed, as well as the channel dimension for grayscale images).\n The resulting array has its color channel dimension ordered last to\n fit the requirements of the `matplotlib` library.\n \"\"\"\n\n # `pyplot` expects the channels to come last.\n if get_backend().dim_order == 'channels_first':\n a = a.transpose((0, 2, 3, 1))\n\n n, h, w, c = a.shape\n\n rows = int(np.sqrt(n))\n cols = int(np.ceil(float(n) / rows))\n\n new_a = np.zeros((h * rows, w * cols, c))\n\n for i, x in enumerate(a):\n row = i // cols\n col = i % cols\n new_a[row * h:(row + 1) * h, col * w:(col + 1) * w] = x\n\n return np.squeeze(new_a)\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.Tiler.tile","title":"
tile(a)","text":"
Tiles the given array into a grid that is as square as possible.
Parameters:
Name Type Description Default
a np.ndarray An array of 4D batched image data.
required
Returns:
Type Description
np.ndarray A tiled array of the images from a. The resulting array has rank
np.ndarray 3 for color images, and 2 for grayscale images (the batch dimension
np.ndarray is removed, as well as the channel dimension for grayscale images).
np.ndarray The resulting array has its color channel dimension ordered last to
np.ndarray fit the requirements of the matplotlib library.
Source code in
trulens_explain/trulens/visualizations.py def tile(self, a: np.ndarray) -> np.ndarray:\n\"\"\"\n Tiles the given array into a grid that is as square as possible.\n\n Parameters:\n a:\n An array of 4D batched image data.\n\n Returns:\n A tiled array of the images from `a`. The resulting array has rank\n 3 for color images, and 2 for grayscale images (the batch dimension\n is removed, as well as the channel dimension for grayscale images).\n The resulting array has its color channel dimension ordered last to\n fit the requirements of the `matplotlib` library.\n \"\"\"\n\n # `pyplot` expects the channels to come last.\n if get_backend().dim_order == 'channels_first':\n a = a.transpose((0, 2, 3, 1))\n\n n, h, w, c = a.shape\n\n rows = int(np.sqrt(n))\n cols = int(np.ceil(float(n) / rows))\n\n new_a = np.zeros((h * rows, w * cols, c))\n\n for i, x in enumerate(a):\n row = i // cols\n col = i % cols\n new_a[row * h:(row + 1) * h, col * w:(col + 1) * w] = x\n\n return np.squeeze(new_a)\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.Visualizer","title":"
Visualizer","text":"
Bases: object
Visualizes attributions directly as a color image. Intended particularly for use with input-attributions.
This can also be used for viewing images (rather than attributions).
Source code in
trulens_explain/trulens/visualizations.py class Visualizer(object):\n\"\"\"\n Visualizes attributions directly as a color image. Intended particularly for\n use with input-attributions.\n\n This can also be used for viewing images (rather than attributions).\n \"\"\"\n\n def __init__(\n self,\n combine_channels: bool = False,\n normalization_type: str = None,\n blur: float = 0.,\n cmap: Colormap = None\n ):\n\"\"\"\n Configures the default parameters for the `__call__` method (these can \n be overridden by passing in values to `__call__`).\n\n Parameters:\n combine_channels:\n If `True`, the attributions will be averaged across the channel\n dimension, resulting in a 1-channel attribution map.\n\n normalization_type:\n Specifies one of the following configurations for normalizing\n the attributions (each item is normalized separately):\n\n - `'unsigned_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the attributions by the maximum absolute \n attribution value.\n - `'unsigned_max_positive_centered'`: same as above, but scales\n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5. \n - `'magnitude_max'`: takes the absolute value of the \n attributions, then normalizes the attributions to the range \n [0, 1] by dividing by the maximum absolute attribution value.\n - `'magnitude_sum'`: takes the absolute value of the \n attributions, then scales them such that they sum to 1. If \n this option is used, each channel is normalized separately, \n such that each channel sums to 1.\n - `'signed_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the positive values by the maximum \n positive attribution value and the negative values by the \n minimum negative attribution value.\n - `'signed_max_positive_centered'`: same as above, but scales \n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5.\n - `'signed_sum'`: scales the positive attributions such that \n they sum to 1 and the negative attributions such that they\n scale to -1. If this option is used, each channel is \n normalized separately.\n - `'01'`: normalizes the attributions to the range [0, 1] by \n subtracting the minimum attribution value then dividing by the\n maximum attribution value.\n - `'unnormalized'`: leaves the attributions unaffected.\n\n If `None`, either `'unsigned_max'` (for single-channel data) or \n `'unsigned_max_positive_centered'` (for multi-channel data) is\n used.\n\n blur:\n Gives the radius of a Gaussian blur to be applied to the \n attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels.\n\n cmap: matplotlib.colors.Colormap | str, optional\n Colormap or name of a Colormap to use for the visualization. If \n `None`, the colormap will be chosen based on the normalization \n type. This argument is only used for single-channel data\n (including when `combine_channels` is True).\n \"\"\"\n self.default_combine_channels = combine_channels\n self.default_normalization_type = normalization_type\n self.default_blur = blur\n self.default_cmap = cmap if cmap is not None else self._get_hotcold()\n\n # TODO(klas): in the future we can allow configuring of tiling settings\n # by allowing the user to specify the tiler.\n self.tiler = Tiler()\n\n def __call__(\n self,\n attributions,\n output_file=None,\n imshow=True,\n fig=None,\n return_tiled=False,\n combine_channels=None,\n normalization_type=None,\n blur=None,\n cmap=None\n ) -> np.ndarray:\n\"\"\"\n Visualizes the given attributions.\n\n Parameters:\n attributions:\n A `np.ndarray` containing the attributions to be visualized.\n\n output_file:\n File name to save the visualization image to. If `None`, no\n image will be saved, but the figure can still be displayed.\n\n imshow:\n If true, a the visualization will be displayed. Otherwise the\n figure will not be displayed, but the figure can still be saved.\n\n fig:\n The `pyplot` figure to display the visualization in. If `None`,\n a new figure will be created.\n\n return_tiled:\n If true, the returned array will be in the same shape as the\n visualization, with no batch dimension and the samples in the\n batch tiled along the width and height dimensions. If false, the\n returned array will be reshaped to match `attributions`.\n\n combine_channels:\n If `True`, the attributions will be averaged across the channel\n dimension, resulting in a 1-channel attribution map. If `None`,\n defaults to the value supplied to the constructor.\n\n normalization_type:\n Specifies one of the following configurations for normalizing\n the attributions (each item is normalized separately):\n\n - `'unsigned_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the attributions by the maximum absolute \n attribution value.\n - `'unsigned_max_positive_centered'`: same as above, but scales\n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5. \n - `'magnitude_max'`: takes the absolute value of the \n attributions, then normalizes the attributions to the range \n [0, 1] by dividing by the maximum absolute attribution value.\n - `'magnitude_sum'`: takes the absolute value of the \n attributions, then scales them such that they sum to 1. If \n this option is used, each channel is normalized separately, \n such that each channel sums to 1.\n - `'signed_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the positive values by the maximum \n positive attribution value and the negative values by the \n minimum negative attribution value.\n - `'signed_max_positive_centered'`: same as above, but scales \n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5.\n - `'signed_sum'`: scales the positive attributions such that \n they sum to 1 and the negative attributions such that they\n scale to -1. If this option is used, each channel is \n normalized separately.\n - `'01'`: normalizes the attributions to the range [0, 1] by \n subtracting the minimum attribution value then dividing by the\n maximum attribution value.\n - `'unnormalized'`: leaves the attributions unaffected.\n\n If `None`, defaults to the value supplied to the constructor.\n\n blur:\n Gives the radius of a Gaussian blur to be applied to the \n attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels. If\n `None`, defaults to the value supplied to the constructor.\n\n cmap: matplotlib.colors.Colormap | str, optional\n Colormap or name of a Colormap to use for the visualization. If\n `None`, defaults to the value supplied to the constructor.\n\n Returns:\n A `np.ndarray` array of the numerical representation of the\n attributions as modified for the visualization. This includes \n normalization, blurring, etc.\n \"\"\"\n combine_channels, normalization_type, blur, cmap = self._check_args(\n attributions, combine_channels, normalization_type, blur, cmap\n )\n\n # Combine the channels if specified.\n if combine_channels:\n attributions = attributions.mean(\n axis=get_backend().channel_axis, keepdims=True\n )\n\n # Blur the attributions so the explanation is smoother.\n if blur:\n attributions = self._blur(attributions, blur)\n\n # Normalize the attributions.\n attributions = self._normalize(attributions, normalization_type)\n\n tiled_attributions = self.tiler.tile(attributions)\n\n # Display the figure:\n _fig = plt.figure() if fig is None else fig\n\n plt.axis('off')\n plt.imshow(tiled_attributions, cmap=cmap)\n\n if output_file:\n plt.savefig(output_file, bbox_inches=0)\n\n if imshow:\n plt.show()\n\n elif fig is None:\n plt.close(_fig)\n\n return tiled_attributions if return_tiled else attributions\n\n def _check_args(\n self, attributions, combine_channels, normalization_type, blur, cmap\n ):\n\"\"\"\n Validates the arguments, and sets them to their default values if they\n are not specified.\n \"\"\"\n if attributions.ndim != 4:\n raise ValueError(\n '`Visualizer` is inteded for 4-D image-format data. Given '\n 'input with dimension {}'.format(attributions.ndim)\n )\n\n if combine_channels is None:\n combine_channels = self.default_combine_channels\n\n channel_axis = get_backend().channel_axis\n if not (attributions.shape[channel_axis] in (1, 3, 4) or\n combine_channels):\n\n raise ValueError(\n 'To visualize, attributions must have either 1, 3, or 4 color '\n 'channels, but `Visualizer` got {} channels.\\n'\n 'If you are visualizing an internal layer, consider setting '\n '`combine_channels` to True'.format(\n attributions.shape[channel_axis]\n )\n )\n\n if normalization_type is None:\n normalization_type = self.default_normalization_type\n\n if normalization_type is None:\n if combine_channels or attributions.shape[channel_axis] == 1:\n normalization_type = 'unsigned_max'\n\n else:\n normalization_type = 'unsigned_max_positive_centered'\n\n valid_normalization_types = [\n 'unsigned_max',\n 'unsigned_max_positive_centered',\n 'magnitude_max',\n 'magnitude_sum',\n 'signed_max',\n 'signed_max_positive_centered',\n 'signed_sum',\n '01',\n 'unnormalized',\n ]\n if normalization_type not in valid_normalization_types:\n raise ValueError(\n '`norm` must be None or one of the following options:' +\n ','.join(\n [\n '\\'{}\\''.form(norm_type)\n for norm_type in valid_normalization_types\n ]\n )\n )\n\n if blur is None:\n blur = self.default_blur\n\n if cmap is None:\n cmap = self.default_cmap\n\n return combine_channels, normalization_type, blur, cmap\n\n def _normalize(self, attributions, normalization_type, eps=1e-20):\n channel_axis = get_backend().channel_axis\n if normalization_type == 'unnormalized':\n return attributions\n\n split_by_channel = normalization_type.endswith('sum')\n\n channel_split = [attributions] if split_by_channel else np.split(\n attributions, attributions.shape[channel_axis], axis=channel_axis\n )\n\n normalized_attributions = []\n for c_map in channel_split:\n if normalization_type == 'magnitude_max':\n c_map = np.abs(c_map) / (\n np.abs(c_map).max(axis=(1, 2, 3), keepdims=True) + eps\n )\n\n elif normalization_type == 'magnitude_sum':\n c_map = np.abs(c_map) / (\n np.abs(c_map).sum(axis=(1, 2, 3), keepdims=True) + eps\n )\n\n elif normalization_type.startswith('signed_max'):\n postive_max = c_map.max(axis=(1, 2, 3), keepdims=True)\n negative_max = (-c_map).max(axis=(1, 2, 3), keepdims=True)\n\n # Normalize the postive socres to [0, 1] and negative socresn to\n # [-1, 0].\n normalization_factor = np.where(\n c_map >= 0, postive_max, negative_max\n )\n c_map = c_map / (normalization_factor + eps)\n\n # If positive-centered, normalize so that all scores are in the\n # range [0, 1], with negative scores less than 0.5 and positive\n # scores greater than 0.5.\n if normalization_type.endswith('positive_centered'):\n c_map = c_map / 2. + 0.5\n\n elif normalization_type == 'signed_sum':\n postive_max = np.maximum(c_map, 0).sum(\n axis=(1, 2, 3), keepdims=True\n )\n negative_max = np.maximum(-c_map, 0).sum(\n axis=(1, 2, 3), keepdims=True\n )\n\n # Normalize the postive socres to ensure they sum to 1 and the\n # negative scores to ensure they sum to -1.\n normalization_factor = np.where(\n c_map >= 0, postive_max, negative_max\n )\n c_map = c_map / (normalization_factor + eps)\n\n elif normalization_type.startswith('unsigned_max'):\n c_map = c_map / (\n np.abs(c_map).max(axis=(1, 2, 3), keepdims=True) + eps\n )\n\n # If positive-centered, normalize so that all scores are in the\n # range [0, 1], with negative scores less than 0.5 and positive\n # scores greater than 0.5.\n if normalization_type.endswith('positive_centered'):\n c_map = c_map / 2. + 0.5\n\n elif normalization_type == '01':\n c_map = c_map - c_map.min(axis=(1, 2, 3), keepdims=True)\n c_map = c_map / (c_map.max(axis=(1, 2, 3), keepdims=True) + eps)\n\n normalized_attributions.append(c_map)\n\n return np.concatenate(normalized_attributions, axis=channel_axis)\n\n def _blur(self, attributions, blur):\n for i in range(attributions.shape[0]):\n attributions[i] = gaussian_filter(attributions[i], blur)\n\n return attributions\n\n def _get_hotcold(self):\n hot = cm.get_cmap('hot', 128)\n cool = cm.get_cmap('cool', 128)\n binary = cm.get_cmap('binary', 128)\n hotcold = np.vstack(\n (\n binary(np.linspace(0, 1, 128)) * cool(np.linspace(0, 1, 128)),\n hot(np.linspace(0, 1, 128))\n )\n )\n\n return ListedColormap(hotcold, name='hotcold')\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.Visualizer.__call__","title":"
__call__(attributions, output_file=None, imshow=True, fig=None, return_tiled=False, combine_channels=None, normalization_type=None, blur=None, cmap=None)","text":"
Visualizes the given attributions.
Parameters:
Name Type Description Default
attributions A np.ndarray containing the attributions to be visualized.
required
output_file File name to save the visualization image to. If None, no image will be saved, but the figure can still be displayed.
None imshow If true, a the visualization will be displayed. Otherwise the figure will not be displayed, but the figure can still be saved.
True fig The pyplot figure to display the visualization in. If None, a new figure will be created.
None return_tiled If true, the returned array will be in the same shape as the visualization, with no batch dimension and the samples in the batch tiled along the width and height dimensions. If false, the returned array will be reshaped to match attributions.
False combine_channels If True, the attributions will be averaged across the channel dimension, resulting in a 1-channel attribution map. If None, defaults to the value supplied to the constructor.
None normalization_type Specifies one of the following configurations for normalizing the attributions (each item is normalized separately):
'unsigned_max': normalizes the attributions to the range [-1, 1] by dividing the attributions by the maximum absolute attribution value.'unsigned_max_positive_centered': same as above, but scales the values to the range [0, 1], with negative scores less than 0.5 and positive scores greater than 0.5. 'magnitude_max': takes the absolute value of the attributions, then normalizes the attributions to the range [0, 1] by dividing by the maximum absolute attribution value.'magnitude_sum': takes the absolute value of the attributions, then scales them such that they sum to 1. If this option is used, each channel is normalized separately, such that each channel sums to 1.'signed_max': normalizes the attributions to the range [-1, 1] by dividing the positive values by the maximum positive attribution value and the negative values by the minimum negative attribution value.'signed_max_positive_centered': same as above, but scales the values to the range [0, 1], with negative scores less than 0.5 and positive scores greater than 0.5.'signed_sum': scales the positive attributions such that they sum to 1 and the negative attributions such that they scale to -1. If this option is used, each channel is normalized separately.'01': normalizes the attributions to the range [0, 1] by subtracting the minimum attribution value then dividing by the maximum attribution value.'unnormalized': leaves the attributions unaffected.
If None, defaults to the value supplied to the constructor.
None blur Gives the radius of a Gaussian blur to be applied to the attributions before visualizing. This can be used to help focus on salient regions rather than specific salient pixels. If None, defaults to the value supplied to the constructor.
None cmap matplotlib.colors.Colormap | str, optional Colormap or name of a Colormap to use for the visualization. If None, defaults to the value supplied to the constructor.
None Returns:
Type Description
np.ndarray A np.ndarray array of the numerical representation of the
np.ndarray attributions as modified for the visualization. This includes
np.ndarray normalization, blurring, etc.
Source code in
trulens_explain/trulens/visualizations.py def __call__(\n self,\n attributions,\n output_file=None,\n imshow=True,\n fig=None,\n return_tiled=False,\n combine_channels=None,\n normalization_type=None,\n blur=None,\n cmap=None\n) -> np.ndarray:\n\"\"\"\n Visualizes the given attributions.\n\n Parameters:\n attributions:\n A `np.ndarray` containing the attributions to be visualized.\n\n output_file:\n File name to save the visualization image to. If `None`, no\n image will be saved, but the figure can still be displayed.\n\n imshow:\n If true, a the visualization will be displayed. Otherwise the\n figure will not be displayed, but the figure can still be saved.\n\n fig:\n The `pyplot` figure to display the visualization in. If `None`,\n a new figure will be created.\n\n return_tiled:\n If true, the returned array will be in the same shape as the\n visualization, with no batch dimension and the samples in the\n batch tiled along the width and height dimensions. If false, the\n returned array will be reshaped to match `attributions`.\n\n combine_channels:\n If `True`, the attributions will be averaged across the channel\n dimension, resulting in a 1-channel attribution map. If `None`,\n defaults to the value supplied to the constructor.\n\n normalization_type:\n Specifies one of the following configurations for normalizing\n the attributions (each item is normalized separately):\n\n - `'unsigned_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the attributions by the maximum absolute \n attribution value.\n - `'unsigned_max_positive_centered'`: same as above, but scales\n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5. \n - `'magnitude_max'`: takes the absolute value of the \n attributions, then normalizes the attributions to the range \n [0, 1] by dividing by the maximum absolute attribution value.\n - `'magnitude_sum'`: takes the absolute value of the \n attributions, then scales them such that they sum to 1. If \n this option is used, each channel is normalized separately, \n such that each channel sums to 1.\n - `'signed_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the positive values by the maximum \n positive attribution value and the negative values by the \n minimum negative attribution value.\n - `'signed_max_positive_centered'`: same as above, but scales \n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5.\n - `'signed_sum'`: scales the positive attributions such that \n they sum to 1 and the negative attributions such that they\n scale to -1. If this option is used, each channel is \n normalized separately.\n - `'01'`: normalizes the attributions to the range [0, 1] by \n subtracting the minimum attribution value then dividing by the\n maximum attribution value.\n - `'unnormalized'`: leaves the attributions unaffected.\n\n If `None`, defaults to the value supplied to the constructor.\n\n blur:\n Gives the radius of a Gaussian blur to be applied to the \n attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels. If\n `None`, defaults to the value supplied to the constructor.\n\n cmap: matplotlib.colors.Colormap | str, optional\n Colormap or name of a Colormap to use for the visualization. If\n `None`, defaults to the value supplied to the constructor.\n\n Returns:\n A `np.ndarray` array of the numerical representation of the\n attributions as modified for the visualization. This includes \n normalization, blurring, etc.\n \"\"\"\n combine_channels, normalization_type, blur, cmap = self._check_args(\n attributions, combine_channels, normalization_type, blur, cmap\n )\n\n # Combine the channels if specified.\n if combine_channels:\n attributions = attributions.mean(\n axis=get_backend().channel_axis, keepdims=True\n )\n\n # Blur the attributions so the explanation is smoother.\n if blur:\n attributions = self._blur(attributions, blur)\n\n # Normalize the attributions.\n attributions = self._normalize(attributions, normalization_type)\n\n tiled_attributions = self.tiler.tile(attributions)\n\n # Display the figure:\n _fig = plt.figure() if fig is None else fig\n\n plt.axis('off')\n plt.imshow(tiled_attributions, cmap=cmap)\n\n if output_file:\n plt.savefig(output_file, bbox_inches=0)\n\n if imshow:\n plt.show()\n\n elif fig is None:\n plt.close(_fig)\n\n return tiled_attributions if return_tiled else attributions\n
"},{"location":"trulens_explain/api/visualizations/#trulens_explain.trulens.visualizations.Visualizer.__init__","title":"
__init__(combine_channels=False, normalization_type=None, blur=0.0, cmap=None)","text":"
Configures the default parameters for the __call__ method (these can be overridden by passing in values to __call__).
Parameters:
Name Type Description Default
combine_channels bool If True, the attributions will be averaged across the channel dimension, resulting in a 1-channel attribution map.
False normalization_type str Specifies one of the following configurations for normalizing the attributions (each item is normalized separately):
'unsigned_max': normalizes the attributions to the range [-1, 1] by dividing the attributions by the maximum absolute attribution value.'unsigned_max_positive_centered': same as above, but scales the values to the range [0, 1], with negative scores less than 0.5 and positive scores greater than 0.5. 'magnitude_max': takes the absolute value of the attributions, then normalizes the attributions to the range [0, 1] by dividing by the maximum absolute attribution value.'magnitude_sum': takes the absolute value of the attributions, then scales them such that they sum to 1. If this option is used, each channel is normalized separately, such that each channel sums to 1.'signed_max': normalizes the attributions to the range [-1, 1] by dividing the positive values by the maximum positive attribution value and the negative values by the minimum negative attribution value.'signed_max_positive_centered': same as above, but scales the values to the range [0, 1], with negative scores less than 0.5 and positive scores greater than 0.5.'signed_sum': scales the positive attributions such that they sum to 1 and the negative attributions such that they scale to -1. If this option is used, each channel is normalized separately.'01': normalizes the attributions to the range [0, 1] by subtracting the minimum attribution value then dividing by the maximum attribution value.'unnormalized': leaves the attributions unaffected.
If None, either 'unsigned_max' (for single-channel data) or 'unsigned_max_positive_centered' (for multi-channel data) is used.
None blur float Gives the radius of a Gaussian blur to be applied to the attributions before visualizing. This can be used to help focus on salient regions rather than specific salient pixels.
0.0 cmap Colormap matplotlib.colors.Colormap | str, optional Colormap or name of a Colormap to use for the visualization. If None, the colormap will be chosen based on the normalization type. This argument is only used for single-channel data (including when combine_channels is True).
None Source code in
trulens_explain/trulens/visualizations.py def __init__(\n self,\n combine_channels: bool = False,\n normalization_type: str = None,\n blur: float = 0.,\n cmap: Colormap = None\n):\n\"\"\"\n Configures the default parameters for the `__call__` method (these can \n be overridden by passing in values to `__call__`).\n\n Parameters:\n combine_channels:\n If `True`, the attributions will be averaged across the channel\n dimension, resulting in a 1-channel attribution map.\n\n normalization_type:\n Specifies one of the following configurations for normalizing\n the attributions (each item is normalized separately):\n\n - `'unsigned_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the attributions by the maximum absolute \n attribution value.\n - `'unsigned_max_positive_centered'`: same as above, but scales\n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5. \n - `'magnitude_max'`: takes the absolute value of the \n attributions, then normalizes the attributions to the range \n [0, 1] by dividing by the maximum absolute attribution value.\n - `'magnitude_sum'`: takes the absolute value of the \n attributions, then scales them such that they sum to 1. If \n this option is used, each channel is normalized separately, \n such that each channel sums to 1.\n - `'signed_max'`: normalizes the attributions to the range \n [-1, 1] by dividing the positive values by the maximum \n positive attribution value and the negative values by the \n minimum negative attribution value.\n - `'signed_max_positive_centered'`: same as above, but scales \n the values to the range [0, 1], with negative scores less than\n 0.5 and positive scores greater than 0.5.\n - `'signed_sum'`: scales the positive attributions such that \n they sum to 1 and the negative attributions such that they\n scale to -1. If this option is used, each channel is \n normalized separately.\n - `'01'`: normalizes the attributions to the range [0, 1] by \n subtracting the minimum attribution value then dividing by the\n maximum attribution value.\n - `'unnormalized'`: leaves the attributions unaffected.\n\n If `None`, either `'unsigned_max'` (for single-channel data) or \n `'unsigned_max_positive_centered'` (for multi-channel data) is\n used.\n\n blur:\n Gives the radius of a Gaussian blur to be applied to the \n attributions before visualizing. This can be used to help focus\n on salient regions rather than specific salient pixels.\n\n cmap: matplotlib.colors.Colormap | str, optional\n Colormap or name of a Colormap to use for the visualization. If \n `None`, the colormap will be chosen based on the normalization \n type. This argument is only used for single-channel data\n (including when `combine_channels` is True).\n \"\"\"\n self.default_combine_channels = combine_channels\n self.default_normalization_type = normalization_type\n self.default_blur = blur\n self.default_cmap = cmap if cmap is not None else self._get_hotcold()\n\n # TODO(klas): in the future we can allow configuring of tiling settings\n # by allowing the user to specify the tiler.\n self.tiler = Tiler()\n
"}]}
\ No newline at end of file
diff --git a/sitemap.xml b/sitemap.xml
index 0f8724efd..d82669d9c 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -1,3 +1,238 @@
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
+
+ None
+ 2023-11-16
+ daily
+
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index a95b94987..323751071 100644
Binary files a/sitemap.xml.gz and b/sitemap.xml.gz differ
diff --git a/stylesheets/style.css b/stylesheets/style.css
index 287c1050d..b5d378632 100644
--- a/stylesheets/style.css
+++ b/stylesheets/style.css
@@ -635,7 +635,8 @@ p {
position: fixed;
top: calc(calc(var(--gap-lg) * 2 + 32px) + 0.5rem);
left: 0;
- width: 100vw;
+ width: 100%;
+ height: min-content;
background-color: var(--color-navigation);
box-shadow: 0px 4px 8px rgba(0, 0, 0, 0.08);
list-style-type: none;
diff --git a/trulens_eval/CONTRIBUTING/index.html b/trulens_eval/CONTRIBUTING/index.html
index c78d14d85..137415301 100644
--- a/trulens_eval/CONTRIBUTING/index.html
+++ b/trulens_eval/CONTRIBUTING/index.html
@@ -16,9 +16,8 @@
-
-
+
@@ -26,18 +25,15 @@
-
+
-
+
-
-
-
@@ -69,7 +65,7 @@
-
+
@@ -101,7 +97,6 @@