> For the complete documentation index, see [llms.txt](https://docs.interactive.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.interactive.ai/sdk/scoring.md).

# Scoring

## Overview

Attach numeric, boolean, or categorical scores to traces and spans.

`create_score` posts a score to any trace or observation by ID. `score_current_span` and `score_current_trace` resolve the active OTel context automatically.

***

## `create_score` [(source)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L1934)

Create a score for a specific trace or observation.

This method creates a score for evaluating a InteractiveAI trace or observation. Scores can be used to track quality metrics, user feedback, or automated evaluations.

```python
create_score(
    *,
    name: str,
    value: Union[float, str],
    session_id: str | None = None,
    dataset_run_id: str | None = None,
    trace_id: str | None = None,
    observation_id: str | None = None,
    score_id: str | None = None,
    data_type: Literal['NUMERIC', 'CATEGORICAL', 'BOOLEAN'] | None = None,
    comment: str | None = None,
    config_id: str | None = None,
    metadata: Any | None = None,
    timestamp: datetime | None = None,
) -> None
```

**Parameters**

* `name` — Name of the score (e.g., "relevance", "accuracy")
* `value` — Score value (can be numeric for NUMERIC/BOOLEAN types or string for CATEGORICAL)
* `session_id` — ID of the InteractiveAI session to associate the score with
* `dataset_run_id` — ID of the InteractiveAI dataset run to associate the score with
* `trace_id` — ID of the InteractiveAI trace to associate the score with
* `observation_id` — Optional ID of the specific observation to score. Trace ID must be provided too.
* `score_id` — Optional custom ID for the score (auto-generated if not provided)
* `data_type` — Type of score (NUMERIC, BOOLEAN, or CATEGORICAL)
* `comment` — Optional comment or explanation for the score
* `config_id` — Optional ID of a score config defined in InteractiveAI
* `metadata` — Optional metadata to be attached to the score
* `timestamp` — Optional timestamp for the score (defaults to current UTC time)

**Example**

```python
# Create a numeric score for accuracy
interactiveai.create_score(
    name="accuracy",
    value=0.92,
    trace_id="abcdef1234567890abcdef1234567890",
    data_type="NUMERIC",
    comment="High accuracy with minor irrelevant details"
)

# Create a categorical score for sentiment
interactiveai.create_score(
    name="sentiment",
    value="positive",
    trace_id="abcdef1234567890abcdef1234567890",
    observation_id="abcdef1234567890",
    data_type="CATEGORICAL"
)
```

***

## `score_current_span` [(source)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L2029)

Create a score for the current active span.

This method scores the currently active span in the context. It's a convenient way to score the current operation without needing to know its trace and span IDs.

```python
score_current_span(
    *,
    name: str,
    value: Union[float, str],
    score_id: str | None = None,
    data_type: Literal['NUMERIC', 'CATEGORICAL', 'BOOLEAN'] | None = None,
    comment: str | None = None,
    config_id: str | None = None,
) -> None
```

**Parameters**

* `name` — Name of the score (e.g., "relevance", "accuracy")
* `value` — Score value (can be numeric for NUMERIC/BOOLEAN types or string for CATEGORICAL)
* `score_id` — Optional custom ID for the score (auto-generated if not provided)
* `data_type` — Type of score (NUMERIC, BOOLEAN, or CATEGORICAL)
* `comment` — Optional comment or explanation for the score
* `config_id` — Optional ID of a score config defined in InteractiveAI

**Example**

```python
with interactiveai.start_as_current_generation(name="answer-query") as generation:
    # Generate answer
    response = generate_answer(...)
    generation.update(output=response)

    # Score the generation
    interactiveai.score_current_span(
        name="relevance",
        value=0.85,
        data_type="NUMERIC",
        comment="Mostly relevant but contains some tangential information"
    )
```

***

## `score_current_trace` [(source)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L2101)

Create a score for the current trace.

This method scores the trace of the currently active span. Unlike score\_current\_span, this method associates the score with the entire trace rather than a specific span. It's useful for scoring overall performance or quality of the entire operation.

```python
score_current_trace(
    *,
    name: str,
    value: Union[float, str],
    score_id: str | None = None,
    data_type: Literal['NUMERIC', 'CATEGORICAL', 'BOOLEAN'] | None = None,
    comment: str | None = None,
    config_id: str | None = None,
) -> None
```

**Parameters**

* `name` — Name of the score (e.g., "user\_satisfaction", "overall\_quality")
* `value` — Score value (can be numeric for NUMERIC/BOOLEAN types or string for CATEGORICAL)
* `score_id` — Optional custom ID for the score (auto-generated if not provided)
* `data_type` — Type of score (NUMERIC, BOOLEAN, or CATEGORICAL)
* `comment` — Optional comment or explanation for the score
* `config_id` — Optional ID of a score config defined in InteractiveAI

**Example**

```python
with interactiveai.start_as_current_span(name="process-user-request") as span:
    # Process request
    result = process_complete_request()
    span.update(output=result)

    # Score the overall trace
    interactiveai.score_current_trace(
        name="overall_quality",
        value=0.95,
        data_type="NUMERIC",
        comment="High quality end-to-end response"
    )
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.interactive.ai/sdk/scoring.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.