trulens.apps.llamaindexยถ
trulens.apps.llamaindex
ยถ
Additional Dependency Required
To use this module, you must have the trulens-apps-llamaindex
package installed.
pip install trulens-apps-llamaindex
Classesยถ
WithFeedbackFilterNodes
ยถ
Bases: RetrieverQueryEngine
Attributesยถ
threshold
instance-attribute
ยถ
threshold: float = threshold
A BaseQueryEngine that filters documents using a minimum threshold on a feedback function before returning them.
PARAMETER | DESCRIPTION |
---|---|
feedback
|
use this feedback function to score each document.
|
threshold
|
and keep documents only if their feedback value is at least this threshold.
|
"Using TruLens guardrail context filters with LlamaIndex"
from trulens.apps.llamaindex.guardrails import WithFeedbackFilterNodes
# note: feedback function used for guardrail must only return a score, not also reasons
feedback = (
Feedback(provider.context_relevance)
.on_input()
.on(context)
)
filtered_query_engine = WithFeedbackFilterNodes(query_engine, feedback=feedback, threshold=0.5)
tru_recorder = TruLlama(filtered_query_engine,
app_name="LlamaIndex_App",
app_version="v1_filtered"
)
with tru_recorder as recording:
llm_response = filtered_query_engine.query("What did the author do growing up?")
Functionsยถ
query
ยถ
query(query: QueryBundle, **kwargs) -> List[NodeWithScore]
An extended query method that will:
- Query the engine with the given query bundle (like before).
- Evaluate nodes with a specified feedback function.
- Filter out nodes that do not meet the minimum threshold.
- Synthesize with only the filtered nodes.
PARAMETER | DESCRIPTION |
---|---|
query
|
The query bundle to search for relevant nodes.
TYPE:
|
**kwargs
|
additional keyword arguments.
DEFAULT:
|
RETURNS | DESCRIPTION |
---|---|
List[NodeWithScore]
|
List[NodeWithScore]: a list of filtered, relevant nodes. |
LlamaInstrument
ยถ
Bases: Instrument
Instrumentation for LlamaIndex apps.
Attributesยถ
INSTRUMENT
class-attribute
instance-attribute
ยถ
INSTRUMENT = '__tru_instrumented'
Attribute name to be used to flag instrumented objects/methods/others.
APPS
class-attribute
instance-attribute
ยถ
APPS = '__tru_apps'
Attribute name for storing apps that expect to be notified of calls.
Classesยถ
Default
ยถ
Instrumentation specification for LlamaIndex apps.
MODULES
class-attribute
instance-attribute
ยถMODULES = union(MODULES)
Modules by prefix to instrument.
Note that llama_index uses langchain internally for some things.
CLASSES
class-attribute
instance-attribute
ยถCLASSES = lambda: union(CLASSES())
Classes to instrument.
METHODS
class-attribute
instance-attribute
ยถMETHODS: List[InstrumentedMethod] = METHODS + [
InstrumentedMethod("chat", BaseLLM),
InstrumentedMethod("complete", BaseLLM),
InstrumentedMethod("stream_chat", BaseLLM),
InstrumentedMethod("stream_complete", BaseLLM),
InstrumentedMethod("achat", BaseLLM),
InstrumentedMethod("acomplete", BaseLLM),
InstrumentedMethod("astream_chat", BaseLLM),
InstrumentedMethod("astream_complete", BaseLLM),
InstrumentedMethod("__call__", BaseTool),
InstrumentedMethod("call", BaseTool),
InstrumentedMethod("acall", AsyncBaseTool),
InstrumentedMethod("put", BaseMemory),
InstrumentedMethod("get_response", Refine),
InstrumentedMethod("predict", BaseLLMPredictor),
InstrumentedMethod("apredict", BaseLLMPredictor),
InstrumentedMethod("stream", BaseLLMPredictor),
InstrumentedMethod("astream", BaseLLMPredictor),
InstrumentedMethod("query", BaseQueryEngine),
InstrumentedMethod("aquery", BaseQueryEngine),
InstrumentedMethod("synthesize", BaseQueryEngine),
InstrumentedMethod("asynthesize", BaseQueryEngine),
InstrumentedMethod("chat", BaseChatEngine),
InstrumentedMethod("achat", BaseChatEngine),
InstrumentedMethod("stream_chat", BaseChatEngine),
InstrumentedMethod("astream_chat", BaseChatEngine),
InstrumentedMethod("complete", BaseChatEngine),
InstrumentedMethod("acomplete", BaseChatEngine),
InstrumentedMethod("stream_complete", BaseChatEngine),
InstrumentedMethod("astream_complete", BaseChatEngine),
InstrumentedMethod(
"retrieve", BaseQueryEngine, **_retrieval_span()
),
InstrumentedMethod(
"_retrieve", BaseQueryEngine, **_retrieval_span()
),
InstrumentedMethod(
"_aretrieve", BaseQueryEngine, **_retrieval_span()
),
InstrumentedMethod(
"retrieve", BaseRetriever, **_retrieval_span()
),
InstrumentedMethod(
"_retrieve", BaseRetriever, **_retrieval_span()
),
InstrumentedMethod(
"_aretrieve", BaseRetriever, **_retrieval_span()
),
InstrumentedMethod(
"retrieve",
WithFeedbackFilterNodes,
**_retrieval_span()
),
InstrumentedMethod(
"_retrieve",
WithFeedbackFilterNodes,
**_retrieval_span()
),
InstrumentedMethod(
"_aretrieve",
WithFeedbackFilterNodes,
**_retrieval_span()
),
InstrumentedMethod(
"_postprocess_nodes", BaseNodePostprocessor
),
InstrumentedMethod(
"_run_component", QueryEngineComponent
),
InstrumentedMethod(
"_run_component", RetrieverComponent
),
]
Methods to instrument.
Functionsยถ
print_instrumentation
ยถ
print_instrumentation() -> None
Print out description of the modules, classes, methods this class will instrument.
to_instrument_object
ยถ
Determine whether the given object should be instrumented.
to_instrument_class
ยถ
Determine whether the given class should be instrumented.
to_instrument_module
ยถ
Determine whether a module with the given (full) name should be instrumented.
_have_context
staticmethod
ยถ
_have_context() -> bool
Determine whether context vars we need for recording are available.
tracked_method_wrapper
ยถ
tracked_method_wrapper(
query: Lens,
func: Callable,
method_name: str,
cls: type,
obj: object,
span_type: Optional[SpanType] = None,
attributes: Optional[Attributes] = None,
must_be_first_wrapper: bool = False,
)
Wrap a method to capture its inputs/outputs/errors.
instrument_method
ยถ
Instrument a method.
instrument_class
ยถ
instrument_class(cls)
Instrument the given class cls
's new method.
This is done so we can be aware when new instances are created and is needed for wrapped methods that dynamically create instances of classes we wish to instrument. As they will not be visible at the time we wrap the app, we need to pay attention to new to make a note of them when they are created and the creator's path. This path will be used to place these new instances in the app json structure.
TruLlama
ยถ
Bases: App
Recorder for LlamaIndex applications.
This recorder is designed for LlamaIndex apps, providing a way to instrument, log, and evaluate their behavior.
Example: "Creating a LlamaIndex application"
Consider an example LlamaIndex application. For the complete code
example, see [LlamaIndex
Quickstart](https://docs.llamaindex.ai/en/stable/getting_started/starter_example.html).
```python
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
documents = SimpleDirectoryReader("data").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()
```
Feedback functions can utilize the specific context produced by the
application's retriever. This is achieved using the select_context
method,
which then can be used by a feedback selector, such as on(context)
.
Example: "Defining a feedback function"
```python
from trulens.providers.openai import OpenAI
from trulens.core import Feedback
import numpy as np
# Select context to be used in feedback.
from trulens.apps.llamaindex import TruLlama
context = TruLlama.select_context(query_engine)
# Use feedback
f_context_relevance = (
Feedback(provider.context_relevance_with_context_reasons)
.on_input()
.on(context) # Refers to context defined from `select_context`
.aggregate(np.mean)
)
```
The application can be wrapped in a TruLlama
recorder to provide logging
and evaluation upon the application's use.
Example: "Using the TruLlama
recorder"
```python
from trulens.apps.llamaindex import TruLlama
# f_lang_match, f_qa_relevance, f_context_relevance are feedback functions
tru_recorder = TruLlama(query_engine,
app_name='LlamaIndex",
app_version="base',
feedbacks=[f_lang_match, f_qa_relevance, f_context_relevance])
with tru_recorder as recording:
query_engine.query("What is llama index?")
```
Feedback functions can utilize the specific context produced by the
application's query engine. This is achieved using the select_context
method, which then can be used by a feedback selector, such as
on(context)
.
Further information about LlamaIndex apps can be found on the ๐ฆ LlamaIndex Documentation page.
PARAMETER | DESCRIPTION |
---|---|
app
|
A LlamaIndex application.
TYPE:
|
**kwargs
|
Additional arguments to pass to App and AppDefinition.
TYPE:
|
Attributesยถ
_context_contexts
class-attribute
instance-attribute
ยถ
_context_contexts = ContextVar(
"context_contexts", default=set()
)
ContextVars for storing collections of RecordingContext .
_stack_contexts
class-attribute
instance-attribute
ยถ
_stack_contexts = ContextVar('stack_contexts', default={})
ContextVars for storing call stacks.
tru_class_info
instance-attribute
ยถ
tru_class_info: Class
Class information of this pydantic object for use in deserialization.
Using this odd key to not pollute attribute names in whatever class we mix this into. Should be the same as CLASS_INFO.
app_id
class-attribute
instance-attribute
ยถ
Unique identifier for this app.
Computed deterministically from app_name and app_version. Leaving it here for it to be dumped when serializing. Also making it read-only as it should not be changed after creation.
app_version
instance-attribute
ยถ
app_version: AppVersion
Version tag for this app. Default is "base".
feedback_definitions
class-attribute
instance-attribute
ยถ
feedback_definitions: Sequence[FeedbackDefinitionID] = []
Feedback functions to evaluate on each record.
feedback_mode
class-attribute
instance-attribute
ยถ
feedback_mode: FeedbackMode = WITH_APP_THREAD
How to evaluate feedback functions upon producing a record.
record_ingest_mode
instance-attribute
ยถ
record_ingest_mode: RecordIngestMode = record_ingest_mode
Mode of records ingestion.
root_class
instance-attribute
ยถ
root_class: Class
Class of the main instrumented object.
Ideally this would be a ClassVar but since we want to check this without instantiating the subclass of AppDefinition that would define it, we cannot use ClassVar.
initial_app_loader_dump
class-attribute
instance-attribute
ยถ
initial_app_loader_dump: Optional[SerialBytes] = None
Serialization of a function that loads an app.
Dump is of the initial app state before any invocations. This can be used to create a new session.
Warning
Experimental work in progress.
app_extra_json
instance-attribute
ยถ
app_extra_json: JSON
Info to store about the app and to display in dashboard.
This can be used even if app itself cannot be serialized. app_extra_json
,
then, can stand in place for whatever data the user might want to keep track
of about the app.
feedbacks
class-attribute
instance-attribute
ยถ
Feedback functions to evaluate on each record.
session
class-attribute
instance-attribute
ยถ
session: TruSession = Field(
default_factory=TruSession, exclude=True
)
Session for this app.
main_method_name
class-attribute
instance-attribute
ยถ
Name of the main method of the app to be recorded. For serialization and this is required for OTEL.
instrument
class-attribute
instance-attribute
ยถ
instrument: Optional[Instrument] = Field(None, exclude=True)
Instrumentation class.
This is needed for serialization as it tells us which objects we want to be included in the json representation of this app.
recording_contexts
class-attribute
instance-attribute
ยถ
recording_contexts: ContextVar[_RecordingContext] = Field(
None, exclude=True
)
Sequences of records produced by the this class used as a context manager are stored in a RecordingContext.
Using a context var so that context managers can be nested.
instrumented_methods
class-attribute
instance-attribute
ยถ
instrumented_methods: Dict[int, Dict[Callable, Lens]] = (
Field(exclude=True, default_factory=dict)
)
Mapping of instrumented methods (by id(.) of owner object and the function) to their path in this app.
records_with_pending_feedback_results
class-attribute
instance-attribute
ยถ
records_with_pending_feedback_results: BlockingSet[
Record
] = Field(exclude=True, default_factory=BlockingSet)
Records produced by this app which might have yet to finish feedback runs.
manage_pending_feedback_results_thread
class-attribute
instance-attribute
ยถ
Thread for manager of pending feedback results queue.
See _manage_pending_feedback_results.
selector_check_warning
class-attribute
instance-attribute
ยถ
selector_check_warning: bool = False
Issue warnings when selectors are not found in the app with a placeholder record.
If False, constructor will raise an error instead.
selector_nocheck
class-attribute
instance-attribute
ยถ
selector_nocheck: bool = False
Ignore selector checks entirely.
This may be necessary 1if the expected record content cannot be determined before it is produced.
Functionsยถ
on_method_instrumented
ยถ
Called by instrumentation system for every function requested to be instrumented by this app.
get_method_path
ยถ
Get the path of the instrumented function method
relative to this
app.
get_methods_for_func
ยถ
Get the methods (rather the inner functions) matching the given
func
and the path of each.
on_new_record
ยถ
on_new_record(func) -> Iterable[_RecordingContext]
Called at the start of record creation.
on_add_record
ยถ
on_add_record(
ctx: _RecordingContext,
func: Callable,
sig: Signature,
bindings: BoundArguments,
ret: Any,
error: Any,
perf: Perf,
cost: Cost,
existing_record: Optional[Record] = None,
final: bool = False,
) -> Record
Called by instrumented methods if they use _new_record to construct a "record call list.
load
staticmethod
ยถ
load(obj, *args, **kwargs)
Deserialize/load this object using the class information in tru_class_info to lookup the actual class that will do the deserialization.
model_validate
classmethod
ยถ
model_validate(*args, **kwargs) -> Any
Deserialized a jsonized version of the app into the instance of the class it was serialized from.
Note
This process uses extra information stored in the jsonized object and handled by WithClassInfo.
continue_session
staticmethod
ยถ
continue_session(
app_definition_json: JSON, app: Any
) -> AppDefinition
Instantiate the given app
with the given state
app_definition_json
.
Warning
This is an experimental feature with ongoing work.
RETURNS | DESCRIPTION |
---|---|
AppDefinition
|
A new |
new_session
staticmethod
ยถ
new_session(
app_definition_json: JSON,
initial_app_loader: Optional[Callable] = None,
) -> AppDefinition
Create an app instance at the start of a session.
Warning
This is an experimental feature with ongoing work.
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).
_submit_feedback_functions
staticmethod
ยถ
_submit_feedback_functions(
record: Record,
feedback_functions: Sequence[Feedback],
connector: DBConnector,
app: Optional[AppDefinition] = None,
on_done: Optional[
Callable[
[Union[FeedbackResult, Future[FeedbackResult]]],
None,
]
] = None,
) -> List[Tuple[Feedback, Future[FeedbackResult]]]
Schedules to run the given feedback functions.
PARAMETER | DESCRIPTION |
---|---|
record
|
The record on which to evaluate the feedback functions.
TYPE:
|
feedback_functions
|
A collection of feedback functions to evaluate. |
connector
|
The database connector to use.
TYPE:
|
app
|
The app that produced the given record. If not provided, it is
looked up from the database of this
TYPE:
|
on_done
|
A callback to call when each feedback function is done.
TYPE:
|
Returns:
List[Tuple[Feedback, Future[FeedbackResult]]]
Produces a list of tuples where the first item in each tuple is the
feedback function and the second is the future of the feedback result.
get_loadable_apps
staticmethod
ยถ
get_loadable_apps()
Gets a list of all of the loadable apps.
Warning
This is an experimental feature with ongoing work.
This is those that have initial_app_loader_dump
set.
_start_manage_pending_feedback_results
ยถ
_start_manage_pending_feedback_results() -> None
Start the thread that manages the queue of records with pending feedback results.
This is meant to be run permanently in a separate thread. It will
remove records from the set records_with_pending_feedback_results
as
their feedback results are computed.
_manage_pending_feedback_results
staticmethod
ยถ
Manage the queue of records with pending feedback results.
This is meant to be run permanently in a separate thread. It will remove records from the set records_with_pending_feedback_results as their feedback results are computed.
wait_for_feedback_results
ยถ
Wait for all feedbacks functions to complete.
This applies to all feedbacks on all records produced by this app. This call will block until finished and if new records are produced while this is running, it will include them.
_tru_post_init
ยถ
_tru_post_init()
Database-related initialization and additional data checks.
DB
- Insert the app into the database.
- Insert feedback function definitions into the database.
Checks
- In deferred mode, try to serialize and deserialize feedback functions.
- Check that feedback function selectors are likely to refer to expected app or record components.
_extract_content
ยถ
_extract_content(value, content_keys=['content'])
Extracts the 'content' from various data types commonly used by libraries like OpenAI, Canopy, LiteLLM, etc. This method navigates nested data structures (pydantic models, dictionaries, lists) to retrieve the 'content' field. If 'content' is not directly available, it attempts to extract from known structures like 'choices' in a ChatResponse. This standardizes extracting relevant text or data from complex API responses or internal data representations.
PARAMETER | DESCRIPTION |
---|---|
value
|
The input data to extract content from. Can be a pydantic model, dictionary, list, or basic data type.
|
RETURNS | DESCRIPTION |
---|---|
The extracted content, which may be a single value, a list of values, |
|
or a nested structure with content extracted from all levels. |
_check_instrumented
ยถ
_check_instrumented(func)
Issue a warning and some instructions if a function that has not been
instrumented is being used in a with_
call.
awith_
async
ยถ
awith_(
func: CallableMaybeAwaitable[A, T], *args, **kwargs
) -> T
Call the given async func
with the given *args
and **kwargs
while recording, producing func
results.
The record of the computation is available through other means like the
database or dashboard. If you need a record of this execution
immediately, you can use awith_record
or the App
as a context
manager instead.
with_
async
ยถ
with_(func: Callable[[A], T], *args, **kwargs) -> T
Call the given async func
with the given *args
and **kwargs
while recording, producing func
results.
The record of the computation is available through other means like the
database or dashboard. If you need a record of this execution
immediately, you can use awith_record
or the App
as a context
manager instead.
with_record
ยถ
with_record(
func: Callable[[A], T],
*args,
record_metadata: JSON = None,
**kwargs
) -> Tuple[T, Record]
Call the given func
with the given *args
and **kwargs
, producing
its results as well as a record of the execution.
awith_record
async
ยถ
awith_record(
func: Callable[[A], Awaitable[T]],
*args,
record_metadata: JSON = None,
**kwargs
) -> Tuple[T, Record]
Call the given func
with the given *args
and **kwargs
, producing
its results as well as a record of the execution.
_add_future_feedback
ยถ
_add_future_feedback(
future_or_result: Union[
FeedbackResult, Future[FeedbackResult]
]
) -> None
Callback used to add feedback results to the database once they are done.
See _handle_record.
_handle_record
ยถ
_handle_record(
record: Record,
feedback_mode: Optional[FeedbackMode] = None,
) -> Optional[
List[Tuple[Feedback, Future[FeedbackResult]]]
]
Write out record-related info to database if set and schedule feedback functions to be evaluated. If feedback_mode is provided, will use that mode instead of the one provided to constructor.
dummy_record
ยถ
dummy_record(
cost: Cost = Cost(),
perf: Perf = now(),
ts: datetime = now(),
main_input: str = "main_input are strings.",
main_output: str = "main_output are strings.",
main_error: str = "main_error are strings.",
meta: Dict = {"metakey": "meta are dicts"},
tags: str = "tags are strings",
) -> Record
Create a dummy record with some of the expected structure without actually invoking the app.
The record is a guess of what an actual record might look like but will be missing information that can only be determined after a call is made.
All args are Record fields except these:
- `record_id` is generated using the default id naming schema.
- `app_id` is taken from this recorder.
- `calls` field is constructed based on instrumented methods.
instrumented
ยถ
instrumented() -> Iterable[Tuple[Lens, ComponentView]]
Iteration over instrumented components and their categories.
format_instrumented_methods
ยถ
format_instrumented_methods() -> str
Build a string containing a listing of instrumented methods.
print_instrumented_components
ยถ
print_instrumented_components() -> None
Print instrumented components and their categories.
add_run
ยถ
get_run
ยถ
list_runs
ยถ
delete
ยถ
delete() -> None
Delete the snowflake App (external agent) in snowflake. All versions will be removed
delete_version
ยถ
delete_version() -> None
Delete the current version of the snowflake App (external agent) in snowflake. Only the non-default version can be deleted.
select_source_nodes
classmethod
ยถ
select_source_nodes() -> Lens
Get the path to the source nodes in the query output.
wrap_lazy_values
ยถ
wrap_lazy_values(
rets: Any,
wrap: Callable[[T], T],
on_done: Optional[Callable[[T], T]],
context_vars: Optional[ContextVarsOrValues] = None,
) -> Any
Wrap any llamaindex specific lazy values with wrappers that have callback wrap.
select_context
classmethod
ยถ
Get the path to the context in the query output.
main_input
ยถ
main_input(
func: Callable, sig: Signature, bindings: BoundArguments
) -> str
Determine the main input string for the given function func
with
signature sig
if it is to be called with the given bindings
bindings
.
main_output
ยถ
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
.