trulens.core.run

trulens.core.run

Classes

Run

Bases: BaseModel

Attributes

model_config class-attribute

model_config: ConfigDict = ConfigDict(
    arbitrary_types_allowed=True, extra="ignore"
)

Run class for managing run state / attributes in the SDK client.

This model is meant to be used and accessed through methods like describe() (which uses the underlying RunDao) to obtain the run metadata.

Functions

describe

describe() -> dict

Retrieve the metadata of the Run object.

delete

delete() -> None

Delete the run by its name and object name.

start

start(input_df: Optional[DataFrame] = None)

Start the run by invoking the main method of the user's app with the input data.

PARAMETER	DESCRIPTION
input_df	Optional input dataframe. If not provided, data is fetched from the source configured in the run's RunConfig. TYPE: Optional[DataFrame] DEFAULT: None

Note

After the app finishes executing, this method kicks off a Snowflake server-side ingestion stored procedure (start_ingestion_query) asynchronously. The method returns before that ingestion is complete. Calling compute_metrics() immediately after start() may therefore find zero events and silently compute nothing.

Wait until run.get_status() returns RunStatus.INVOCATION_COMPLETED (or another terminal invocation state) before calling compute_metrics(). RecordIngestMode.IMMEDIATE only controls the client-side OTEL span exporter flush and does not guarantee that the server-side ingestion sproc has finished.

compute_metrics

compute_metrics(
    metrics: List[
        Union[str, "metric_module.Metric", MetricConfig]
    ]
) -> str

Compute metrics for the run.

PARAMETER	DESCRIPTION
metrics	List of metrics to compute. Each entry can be: - A str — name of a server-side (Snowflake-hosted) metric. - A :class:~trulens.core.metric.metric.Metric — a client-side custom metric defined with the current API. - A :class:~trulens.core.feedback.custom_metric.MetricConfig — deprecated; use Metric instead. TYPE: List[Union[str, 'metric_module.Metric', MetricConfig]]

RETURNS	DESCRIPTION
str	Status message indicating computation progress.

Note

Snowflake record ingestion triggered by run.start() is asynchronous. Call this method only after run.get_status() indicates ingestion has completed (e.g. RunStatus.INVOCATION_COMPLETED). Calling it too soon after start() may result in 0 events being found and no metrics being computed.

get_records

get_records(
    record_ids: Optional[List[str]] = None,
    offset: Optional[int] = None,
    limit: Optional[int] = None,
) -> DataFrame

A wrapper API around get_records_and_feedback to retrieve and display overview of records from event table of the run. It aggregates summary information of records into a single DataFrame.

PARAMETER	DESCRIPTION
record_ids	Optional list of record IDs to filter by. Defaults to None. TYPE: Optional[List[str]] DEFAULT: None
offset	Record row offset. TYPE: Optional[int] DEFAULT: None
limit	Limit on the number of records to return. TYPE: Optional[int] DEFAULT: None

RETURNS	DESCRIPTION
DataFrame	A DataFrame with the overview of records.

get_record_details

get_record_details(
    record_ids: Optional[List[str]] = None,
    offset: Optional[int] = None,
    limit: Optional[int] = None,
) -> DataFrame

A wrapper API around get_records_and_feedback to retrieve records from event table of the run.

PARAMETER	DESCRIPTION
record_ids	Optional list of record IDs to filter by. Defaults to None. TYPE: Optional[List[str]] DEFAULT: None
offset	Record row offset. TYPE: Optional[int] DEFAULT: None
limit	Limit on the number of records to return. TYPE: Optional[int] DEFAULT: None

RETURNS	DESCRIPTION
DataFrame	A DataFrame with the details of records.

update

update(
    description: Optional[str] = None,
    label: Optional[str] = None,
)

Only description and label are allowed to be updated at the moment.

from_metadata_df classmethod

from_metadata_df(
    metadata_df: DataFrame, extra: Dict[str, Any]
) -> Run

Create a Run instance from a metadata DataFrame returned by the DAO, and enrich it with additional fields (which are not persisted on the server).

PARAMETER	DESCRIPTION
metadata_df	A pandas DataFrame containing run metadata. We assume the first row contains a JSON string in its first cell. TYPE: DataFrame
extra	A dictionary of extra fields to add, such as: { "app": , "main_method_name": , "run_dao": , "object_name":

RETURNS	DESCRIPTION
Run	A validated Run instance.

Functions

validate_dataset_spec

validate_dataset_spec(
    dataset_spec: Dict[str, str]
) -> Dict[str, str]

Validates and normalizes the dataset column specification to ensure it contains only currently supported span attributes and that the keys are in the correct format.

PARAMETER	DESCRIPTION
dataset_spec	The user-provided dictionary with column names. TYPE: Dict[str, str]

RETURNS	DESCRIPTION
Dict[str, str]	A validated and normalized dictionary.

RAISES	DESCRIPTION
ValueError	If any invalid field is present.