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

# Programmatic Scoring

> Attach programmatic scores to traces for evaluation and feedback tracking

PandaProbe lets you attach **scores** to traces programmatically. Scores can represent user feedback, automated quality metrics, or any other evaluation signal you want to persist next to a trace.

> [!NOTE]
>
> Scores are first-class objects on the trace record: you can filter, sort, and build dashboards on them alongside latency, tokens, and cost.

## Basic usage

> [tab] Python
>
> ```python title="Python" theme={null}
> import pandaprobe
>
> pandaprobe.score(
>     trace_id="your-trace-id",
>     name="user_satisfaction",
>     value="0.9",
>     data_type="NUMERIC",
>     reason="User clicked thumbs up",
> )
> ```

> [tab] TypeScript
>
> ```ts title="TypeScript" theme={null}
> import { ScoreDataType, score } from "pandaprobe";
>
> score("your-trace-id", "user_satisfaction", "0.9", {
>   dataType: ScoreDataType.NUMERIC,
>   reason: "User clicked thumbs up",
> });
> ```

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `trace_id` | `str` or `UUID` | Yes | The trace to score |
| `name` | `str` | Yes | Score name (for example, `accuracy`, `user_satisfaction`) |
| `value` | `str` | Yes | The score value (always passed as a string) |
| `data_type` | `str` | No | One of `NUMERIC`, `BOOLEAN`, `CATEGORICAL`. Default: `NUMERIC` |
| `reason` | `str` or `None` | No | Human-readable explanation for the score |
| `metadata` | `dict` or `None` | No | Arbitrary key-value pairs |

TypeScript passes the first three values positionally and uses a camelCase options object: `score(traceId, name, value, {dataType, reason, metadata})`.

## Score data types (`ScoreDataType`)

> [tab] NUMERIC
>
> A numeric value between 0 and 1 (for example, `"0.95"`). Use for normalized metrics such as accuracy or satisfaction scores.

> [tab] BOOLEAN
>
> A boolean value (`"true"` or `"false"`). Use for pass/fail checks.

> [tab] CATEGORICAL
>
> A category label (for example, `"positive"`, `"neutral"`, `"negative"`). Use for classification-style scores.

> [!NOTE]
>
> `value` is always a string at the API boundary so serialization stays consistent across languages and storage backends; parse according to `data_type` in your pipelines.

## Getting the trace ID

From a context manager:

```python title="Python" theme={null}
with pandaprobe.start_trace("my-agent") as t:
    trace_id = t.trace_id
    # ... run your agent ...

pandaprobe.score(trace_id=trace_id, name="quality", value="0.8")
```

```ts title="TypeScript" theme={null}
import { score, withTrace } from "pandaprobe";

let traceId = "";
await withTrace("my-agent", async (trace) => {
  traceId = trace.traceId;
  // Run your agent.
});

score(traceId, "quality", "0.8");
```

> [!TIP]
>
> When using wrappers, traces are created automatically. Use sessions to group related traces and score them via the PandaProbe API or dashboard.

## Multiple scores per trace

```python title="Python" theme={null}
pandaprobe.score(trace_id=tid, name="relevance", value="0.9", data_type="NUMERIC")
pandaprobe.score(trace_id=tid, name="hallucination_free", value="true", data_type="BOOLEAN")
pandaprobe.score(trace_id=tid, name="sentiment", value="positive", data_type="CATEGORICAL")
```

```ts title="TypeScript" theme={null}
score(traceId, "relevance", "0.9", { dataType: ScoreDataType.NUMERIC });
score(traceId, "hallucination_free", "true", { dataType: ScoreDataType.BOOLEAN });
score(traceId, "sentiment", "positive", { dataType: ScoreDataType.CATEGORICAL });
```


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