---
title: Transcripts
llms-description: "Reading and filtering transcripts for scanning"
---

## Overview

Transcripts are the fundamental input to scanners. The `Transcripts` class represents a collection of transcripts that has been selected for scanning, and supports various filtering operations to refine the collection.

## Reading Transcripts

Use the `transcripts_from()` function to read a collection of `Transcripts`:

``` python
from inspect_scout import transcripts_from

# read from a transcript database on S3
transcripts = transcripts_from("s3://weave-rollouts/cybench")

# read from an Inspect log directory
transcripts = transcripts_from("./logs")
```

The `transcripts_from()` function can read transcripts from either:

1.  A transcript database that contains transcripts you have imported from a variety of sources (Agent traces, RL rollouts, Inspect logs, etc.); or

2.  One or more Inspect log directories that contain Inspect `.eval` logs.

See the sections below on the [Transcripts Database] and [Inspect Eval Logs] for additional details on working with each.

## Filtering Transcripts

If you want to scan only a subset of transcripts, you can use the `.where()` method to narrow down the collection. For example:

``` python
from inspect_scout import transcripts_from, columns as c

transcripts = (
    transcripts_from("./logs")
    .where(c.task_set == "cybench")
    .where(c.model.like("openai/%"))
)
```

See the `Columns` documentation for additional details on supported filtering operations. 

You can also limit the total number of transcripts as well as shuffle the order of transcripts read (both are useful during scanner development when you don't want to process all transcripts). For example:

``` python
from inspect_scout import transcripts_from

transcripts = (
    transcripts_from("./logs")
    .limit(10)
    .shuffle(42)
)
```

## Viewing Transcripts

{{< include _transcript_filtering.md >}}

If you drill into a transcript you can see its messages, events, and other details:

![](images/transcripts-detail.png){.border}


## Transcript Fields

{{< include _transcript_fields.md >}}

## Scanning Transcripts

Once you have established your list of transcripts to scan, just pass them to the `scan()` function:

``` python
from inspect_scout import scan, transcripts_from

from .scanners import ctf_environment, java_tool_calls

scan(
    scanners = [ctf_environment(), java_tool_calls()],
    transcripts = transcripts_from("./logs")
)
```

If you want to do transcript filtering and then invoke your scan from the CLI using `scout scan`, then perform the filtering inside a `@scanjob`. For example:

{{< include _scanjob-transcripts.md >}}

## Inspect Eval Logs

The `transcripts_from()` function can read a collection of transcripts directly from an Inspect log directory. You can specify one or more directories and/or individual log files. For example:

``` python
# read from a log directory
transcripts = transcripts_from("./logs")

# read multiple log directories
transcripts = transcripts_from(["./logs", "./logs2"])

# read from one or more log files
transcripts = transcripts_from(
    ["logs/cybench.eval", "logs/swebench.eval"]
)
```

For Inspect logs, the `metadata` field within `TranscriptInfo` includes fields from eval sample metadata. For example:

``` python
transcript.metadata["sample_id"]        # sample uuid 
transcript.metadata["id"]               # dataset sample id 
transcript.metadata["epoch"]            # sample epoch
transcript.metadata["eval_metadata"]    # eval metadata
transcript.metadata["sample_metadata"]  # sample metadata
transcript.metadata["score_<scorer>"]   # named sample scores
```

See the `LogColumns` class for details on all of the fields included in `transcript.metadata`. Use `log_columns` (aliased to `c` below) to do typesafe filtering for Inspect logs:

``` python
from inspect_scout import transcripts_from, log_columns as c

transcripts = (
    transcripts_from("./logs")
    .where(c.sample_metadata.category == "accounting")
)
```

## Transcripts Database

Scout can analyze transcripts from any source (e.g. Agent traces, RL rollouts, etc.) so long as the transcripts have been organized into a transcripts database. Transcript databases use [Parquet](https://parquet.apache.org) files for storage and can be located in the local filesystem or remote systems like S3.

You can read from a transcript database using the `transcripts_from()` function. For example:

``` python
from inspect_scout import transcripts_from

# read from a transcript database on S3
transcripts = transcripts_from("s3://weave-rollouts/cybench")
```

See the [Transcripts Database](db_overview.qmd) documentation for additional details on creating, managing, and publishing transcript databases.