> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Act on findings from Topics

> Turn topic classifications into action: build evaluation datasets, set up online scoring by classification, and assign matching logs for human review.

The trends Topics surfaces are most useful when you act on them. This guide covers building evaluation datasets from classified logs, scoring logs based on topic classifications, and assigning logs for human review.

## Build datasets from topics

Filter logs by topic to build targeted evaluation datasets.

1. Go to [** Logs**](https://www.braintrust.dev/app/~/logs) and click the search field. Select  **Add a structured filter**.
2. In **Basic**, select ** Topics** and choose the topic you want to filter by.

   Alternately, click **SQL** and enter a filter clause. See the [SQL reference](https://docs.braintrust.dev/reference/sql/examples.md#query-by-classifications) for more query patterns.

   ```sql Filter by specific topic theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
   classifications.Task.label = "Dataset creation"
   ```

   ```sql Filter by multiple topics theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
   classifications.Task.label IN ("Dataset creation", "API errors")
   ```

   ```sql Combine topics across facets theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
   classifications.Task.label = "Checkout flow"
     AND classifications.Sentiment.label = "NEGATIVE"
   ```
3. Select the logs you want to include.
4. Click  **Add to** > **Add to dataset**, then choose an existing dataset or create a new one.

Common use cases:

* "Error investigation" tasks → test your error handling.
* Negative sentiment interactions → improve responses.
* "Pricing questions" → evaluate your pricing explanations.

See [Promote traces from logs](https://docs.braintrust.dev/annotate/datasets/create.md#promote-traces-from-logs) for more on curating datasets from production traces.

## Score logs based on topics

Create scorers that flag logs with negative sentiment, penalize specific issue types, or alert when certain topics appear together.

Example scorer that flags negative checkout experiences:

> [tab] TypeScript
>
> ```typescript topic_scorer.ts theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> import braintrust from "braintrust";
> import { z } from "zod";
>
> const project = braintrust.projects.create({ name: "my-project" });
>
> project.scorers.create({
>   name: "Checkout experience",
>   slug: "checkout-experience",
>   description: "Flag traces with negative checkout experiences",
>   parameters: z.object({
>     trace: z.any(),
>   }),
>   handler: async ({ trace }) => {
>     if (!trace) return { score: null };
>
>     const spans = await trace.getSpans();
>     const rootSpan = spans.find((s) => s.span_id === s.root_span_id);
>     if (!rootSpan) return { score: null };
>
>     const classifications = rootSpan.classifications || {};
>     const taskClassification = (classifications.Task || [{}])[0];
>     const sentimentClassification = (classifications.Sentiment || [{}])[0];
>
>     if (
>       taskClassification.label === "Checkout Flow" &&
>       sentimentClassification.label === "NEGATIVE"
>     ) {
>       return {
>         score: 0,
>         metadata: { reason: "Negative sentiment during checkout" },
>       };
>     }
>
>     return { score: 1 };
>   },
> });
> ```
>
> Save the code to a file and push it:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> bt functions push topic_scorer.ts
> ```

> [tab] Python
>
> ```python topic_scorer.py theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> import braintrust
> from pydantic import BaseModel
>
> project = braintrust.projects.create(name="my-project")
>
> class TraceParams(BaseModel):
>     trace: dict
>
> async def checkout_experience_scorer(trace):
>     if not trace:
>         return {"score": None}
>
>     spans = await trace.get_spans()
>     root_span = next(
>         (s for s in spans if s.get("span_id") == s.get("root_span_id")),
>         None
>     )
>     if not root_span:
>         return {"score": None}
>
>     classifications = root_span.get("classifications", {})
>     task_classification = classifications.get("Task", [{}])[0]
>     sentiment_classification = classifications.get("Sentiment", [{}])[0]
>
>     if (
>         task_classification.get("label") == "Checkout Flow"
>         and sentiment_classification.get("label") == "NEGATIVE"
>     ):
>         return {
>             "score": 0,
>             "metadata": {"reason": "Negative sentiment during checkout"},
>         }
>
>     return {"score": 1}
>
> project.scorers.create(
>     name="Checkout experience",
>     slug="checkout-experience",
>     description="Flag traces with negative checkout experiences",
>     parameters=TraceParams,
>     handler=checkout_experience_scorer,
> )
> ```
>
> Save the code to a file and push it:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> bt functions push topic_scorer.py
> ```

Then configure the automation:

1. Go to ** Settings** > [** Online scoring**](https://www.braintrust.dev/app/~/configuration/automations/online-scoring) and click  **Online scoring rule**.
2. Select your scorer, set **Scope** to ** Trace**, configure the sampling rate, and click **Create automation**.

See [Score online](https://docs.braintrust.dev/evaluate/score-online.md) and [Trace-level scorers](https://docs.braintrust.dev/evaluate/custom-code.md#score-traces) for more details.

## Assign topics for review

Assign logs matching specific topics for human review.

1. Go to [** Logs**](https://www.braintrust.dev/app/~/logs) and click the search field. Select  **Add a structured filter**.
2. In **Basic**, select ** Topics** and choose the topic you want to filter by.

   Alternately, click **SQL** and enter a filter clause. See the [SQL reference](https://docs.braintrust.dev/reference/sql/examples.md#query-by-classifications) for more query patterns.

   ```sql Filter by specific topic theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
   classifications.Task.label = "Dataset creation"
   ```

   ```sql Filter by multiple topics theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
   classifications.Task.label IN ("Dataset creation", "API errors")
   ```

   ```sql Combine topics across facets theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
   classifications.Task.label = "Checkout flow"
     AND classifications.Sentiment.label = "NEGATIVE"
   ```
3. Select the logs you want to assign.
4. Select ** Assign** and choose a team member.

To assign a single trace while exploring the [** Topics**](https://www.braintrust.dev/app/~/topics) page, open the trace in the side panel, select ** Assign**, and choose a team member. Assigning from the Topics page requires the [**Update** permission](https://docs.braintrust.dev/admin/access-control.md#object-permissions) on the project.

> [!TIP]
>
> Team members receive email notifications when rows are assigned to them.

See [Add human feedback](https://docs.braintrust.dev/annotate/human-review.md) for more on human review.

## Next steps

* [Manage Topics](https://docs.braintrust.dev/observe/topics/manage.md) to tune the pipeline that produces these classifications.
* [Custom facets](https://docs.braintrust.dev/observe/topics/custom-facets.md) to define new dimensions to act on.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.