Programmatic Scoring

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.

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

Python
TypeScript

Python

import pandaprobe

pandaprobe.score(
    trace_id="your-trace-id",
    name="user_satisfaction",
    value="0.9",
    data_type="NUMERIC",
    reason="User clicked thumbs up",
)

TypeScript

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`)

NUMERIC
BOOLEAN
CATEGORICAL

A numeric value (for example, "0.95", "4.5"). Use for continuous metrics such as accuracy, latency, or satisfaction scores.

A boolean value ("true" or "false"). Use for pass/fail checks.

A category label (for example, "positive", "neutral", "negative"). Use for classification-style scores.

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

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")

TypeScript

import { score, withTrace } from "pandaprobe";

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

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

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

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")

TypeScript

score(traceId, "relevance", "0.9", { dataType: ScoreDataType.NUMERIC });
score(traceId, "hallucination_free", "true", { dataType: ScoreDataType.BOOLEAN });
score(traceId, "sentiment", "positive", { dataType: ScoreDataType.CATEGORICAL });

Get Started

Tracing

Programmatic Scoring

Basic usage

Parameters

Score data types (`ScoreDataType`)

Getting the trace ID

Multiple scores per trace

​Basic usage

​Parameters

​Score data types (ScoreDataType)

​Getting the trace ID

​Multiple scores per trace

Basic usage

Parameters

Score data types (`ScoreDataType`)

Getting the trace ID

Multiple scores per trace