Evaluators - Arize AX Docs

The evaluators client methods are currently in ALPHA. The API may change without notice. A one-time warning is emitted on first use.

An evaluator scores spans or examples. Each evaluator has one or more immutable versions; a version is either a template (LLM-as-judge) or a code (managed built-in or user-supplied Python) configuration. The Get, Update, Delete, ListVersions, and CreateVersion methods accept either an evaluator name or an ID — when a name is passed, the parent Space (name or ID) is also required so the SDK can resolve the name to a unique ID. GetVersion takes a strict version ID. Set exactly one of VersionConfig.Template or VersionConfig.Code on Create and CreateVersion; within Code, set exactly one of Managed or Custom. Conflicting configurations return evaluators.ErrConflictingVersionConfig or evaluators.ErrConflictingCodeConfig without contacting the server.

List Evaluators

List returns a paginated list of evaluators. Defaults to a page size of 50. Space, when non-empty, filters by space (substring match on space name, or exact match if a base64 resource ID is passed). Signature:

func (c *Client) List(ctx context.Context, req ListRequest) (*EvaluatorList, error)

Usage Example:

package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/evaluators"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Evaluators.List(context.Background(), evaluators.ListRequest{
        Space: "your-space-name-or-id",
        Limit: 25,
    })
    if err != nil {
        var unauthorized *arize.UnauthorizedError
        if errors.As(err, &unauthorized) {
            log.Fatalf("unauthorized: %v", unauthorized)
        }
        log.Fatal(err)
    }

    for _, ev := range resp.Evaluators {
        fmt.Printf("%s: %s (type=%s)\n", ev.Id, ev.Name, ev.Type)
    }
}

Get an Evaluator

Get returns a single evaluator (with one of its versions), resolving by name or ID. When VersionID is set, the response carries that specific version; otherwise the latest version is returned. Signature:

func (c *Client) Get(ctx context.Context, req GetRequest) (*EvaluatorWithVersion, error)

Usage Example:

package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/evaluators"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    ev, err := client.Evaluators.Get(
        context.Background(),
        evaluators.GetRequest{
            Evaluator: "your-evaluator-name-or-id",
            Space:     "your-space-name-or-id",
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("evaluator not found: %v", notFound)
        }
        log.Fatal(err)
    }

    fmt.Printf("evaluator %s: %s (type=%s)\n", ev.Id, ev.Name, ev.Type)
}

Create an Evaluator

Create creates a new evaluator together with its initial version, resolving the parent space by name or ID. The evaluator’s type is derived from Version — set Version.Template for a template (LLM-based) evaluator or Version.Code for a code evaluator (with exactly one of Code.Managed or Code.Custom). Signature:

func (c *Client) Create(ctx context.Context, req CreateRequest) (*EvaluatorWithVersion, error)

Usage Example:

package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/evaluators"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    ev, err := client.Evaluators.Create(
        context.Background(),
        evaluators.CreateRequest{
            Space:       "your-space-name-or-id",
            Name:        "hallucination-judge",
            Description: "scores response groundedness against retrieved context",
            Version: evaluators.VersionConfig{
                CommitMessage: "initial version",
                Template: &evaluators.TemplateConfig{
                    // Template configuration (prompt, LLM config, etc.)
                },
            },
        },
    )
    if err != nil {
        if errors.Is(err, evaluators.ErrConflictingVersionConfig) {
            log.Fatal("set exactly one of Version.Template or Version.Code")
        }
        var conflict *arize.ConflictError
        if errors.As(err, &conflict) {
            log.Fatalf("evaluator already exists: %v", conflict)
        }
        log.Fatal(err)
    }

    fmt.Printf("created evaluator %s\n", ev.Id)
}

Update an Evaluator

Update patches an existing evaluator’s metadata, resolving the target by name or ID, and returns the updated evaluator. Name and Description are pointers — nil preserves the existing value. Returns evaluators.ErrNoUpdateFields without contacting the server when no patch field is set. Signature:

func (c *Client) Update(ctx context.Context, req UpdateRequest) (*Evaluator, error)

Usage Example:

package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/evaluators"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    newName := "renamed-evaluator"
    ev, err := client.Evaluators.Update(
        context.Background(),
        evaluators.UpdateRequest{
            Evaluator: "your-evaluator-name-or-id",
            Space:     "your-space-name-or-id",
            Name:      &newName,
        },
    )
    if err != nil {
        if errors.Is(err, evaluators.ErrNoUpdateFields) {
            log.Fatal("no fields to update")
        }
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("evaluator not found: %v", notFound)
        }
        log.Fatal(err)
    }

    fmt.Printf("updated evaluator %s: %s\n", ev.Id, ev.Name)
}

Delete an Evaluator

Delete removes an evaluator, resolving by name or ID. It returns only an error. Signature:

func (c *Client) Delete(ctx context.Context, req DeleteRequest) error

Usage Example:

package main

import (
    "context"
    "errors"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/evaluators"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    err = client.Evaluators.Delete(
        context.Background(),
        evaluators.DeleteRequest{
            Evaluator: "your-evaluator-name-or-id",
            Space:     "your-space-name-or-id",
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Printf("no evaluator to remove: %v", notFound)
            return
        }
        log.Fatal(err)
    }
}

List Versions

ListVersions returns a paginated list of versions for an evaluator, resolving the evaluator by name or ID. Defaults to a page size of 50. Signature:

func (c *Client) ListVersions(
    ctx context.Context,
    req ListVersionsRequest,
) (*EvaluatorVersionList, error)

Usage Example:

package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/evaluators"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Evaluators.ListVersions(
        context.Background(),
        evaluators.ListVersionsRequest{
            Evaluator: "your-evaluator-name-or-id",
            Space:     "your-space-name-or-id",
            Limit:     25,
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("evaluator not found: %v", notFound)
        }
        log.Fatal(err)
    }

    for _, v := range resp.EvaluatorVersions {
        if d, err := v.Discriminator(); err == nil {
            fmt.Printf("version (type=%s)\n", d)
        }
    }
}

Create a Version

CreateVersion appends a new version to an existing evaluator, resolving the evaluator by name or ID. The new version’s kind (set via Version.Template or Version.Code) must match the parent evaluator’s type. Signature:

func (c *Client) CreateVersion(
    ctx context.Context,
    req CreateVersionRequest,
) (*EvaluatorVersion, error)

Usage Example:

package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/evaluators"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    v, err := client.Evaluators.CreateVersion(
        context.Background(),
        evaluators.CreateVersionRequest{
            Evaluator: "your-evaluator-name-or-id",
            Space:     "your-space-name-or-id",
            Version: evaluators.VersionConfig{
                CommitMessage: "tighten judging rubric",
                Template: &evaluators.TemplateConfig{
                    // Template configuration (prompt, LLM config, etc.)
                },
            },
        },
    )
    if err != nil {
        if errors.Is(err, evaluators.ErrConflictingVersionConfig) {
            log.Fatal("set exactly one of Version.Template or Version.Code")
        }
        var badRequest *arize.BadRequestError
        if errors.As(err, &badRequest) {
            log.Fatalf("invalid version: %v", badRequest)
        }
        log.Fatal(err)
    }

    fmt.Printf("created evaluator version\n")
    if tpl, err := v.AsEvaluatorVersionTemplate(); err == nil {
        fmt.Printf("template commit: %s\n", tpl.CommitMessage)
    }
}

Get a Version

GetVersion returns a single evaluator version by its ID. Version IDs are strict IDs — no name resolution is performed. The returned EvaluatorVersion is a discriminated union — call v.AsEvaluatorVersionTemplate() or v.AsEvaluatorVersionCode() to extract the typed variant after checking the discriminator. Signature:

func (c *Client) GetVersion(ctx context.Context, req GetVersionRequest) (*EvaluatorVersion, error)

Usage Example:

package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/evaluators"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    v, err := client.Evaluators.GetVersion(
        context.Background(),
        evaluators.GetVersionRequest{VersionID: "your-version-id"},
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("version not found: %v", notFound)
        }
        log.Fatal(err)
    }

    d, err := v.Discriminator()
    if err != nil {
        log.Fatal(err)
    }
    switch d {
    case string(evaluators.EvaluatorTypeTemplate):
        tpl, err := v.AsEvaluatorVersionTemplate()
        if err != nil {
            log.Fatal(err)
        }
        fmt.Printf("template version: %s\n", tpl.CommitMessage)
    case string(evaluators.EvaluatorTypeCode):
        code, err := v.AsEvaluatorVersionCode()
        if err != nil {
            log.Fatal(err)
        }
        fmt.Printf("code version: %s\n", code.CommitMessage)
    }
}

​List Evaluators

​Get an Evaluator

​Create an Evaluator

​Update an Evaluator

​Delete an Evaluator

​List Versions

​Create a Version

​Get a Version

List Evaluators

Get an Evaluator

Create an Evaluator

Update an Evaluator

Delete an Evaluator

List Versions

Create a Version

Get a Version