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
import pandaprobe
pandaprobe.score(
trace_id="your-trace-id",
name="user_satisfaction",
value="0.9",
data_type="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 |
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:
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")
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
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")
