phoenix

package module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 17, 2026 License: MIT Imports: 7 Imported by: 0

README

Go SDK for Arize Phoenix

Build Status Lint Status Go Report Card Docs Visualization License

Go SDK for Arize Phoenix - an open-source observability platform for LLM applications.

Installation

go get github.com/agentplexus/go-phoenix

Quick Start

Sending Traces with OTEL
package main

import (
    "context"
    "log"

    phoenixotel "github.com/agentplexus/go-phoenix/otel"
    "go.opentelemetry.io/otel/trace"
)

func main() {
    ctx := context.Background()

    // Register with Phoenix (sends traces to localhost:6006)
    tp, err := phoenixotel.Register(
        phoenixotel.WithProjectName("my-app"),
        phoenixotel.WithBatch(true),
    )
    if err != nil {
        log.Fatal(err)
    }
    defer tp.Shutdown(ctx)

    // Create traces
    tracer := tp.Tracer("my-service")
    ctx, span := tracer.Start(ctx, "llm-call",
        trace.WithAttributes(
            phoenixotel.WithSpanKind(phoenixotel.SpanKindLLM),
            phoenixotel.WithModelName("gpt-4"),
            phoenixotel.WithInput("What is the capital of France?"),
        ),
    )
    // ... do work ...
    span.SetAttributes(phoenixotel.WithOutput("The capital of France is Paris."))
    span.End()
}
Using the REST API Client
package main

import (
    "context"
    "log"

    phoenix "github.com/agentplexus/go-phoenix"
)

func main() {
    ctx := context.Background()

    client, err := phoenix.NewClient(
        phoenix.WithBaseURL("http://localhost:6006"),
    )
    if err != nil {
        log.Fatal(err)
    }

    // List projects
    projects, _, err := client.ListProjects(ctx)
    if err != nil {
        log.Fatal(err)
    }

    for _, p := range projects {
        log.Printf("Project: %s", p.Name)
    }
}
Phoenix Cloud Configuration
tp, err := phoenixotel.Register(
    phoenixotel.WithSpaceID("your-space-id"),  // From app.phoenix.arize.com/s/{space-id}
    phoenixotel.WithAPIKey("your-api-key"),
    phoenixotel.WithProjectName("my-project"),
)

Or via environment variables:

export PHOENIX_SPACE_ID=your-space-id
export PHOENIX_API_KEY=your-api-key
Evaluating LLM Outputs

Metrics are defined in omniobserve/llmops/metrics and can be used with the Phoenix evaluator:

import (
    "context"
    "fmt"
    "os"

    phoenix "github.com/agentplexus/go-phoenix"
    "github.com/agentplexus/go-phoenix/evals"
    "github.com/agentplexus/omniobserve/llmops"
    "github.com/agentplexus/omniobserve/llmops/metrics"
    "github.com/agentplexus/omnillm"
)

func main() {
    ctx := context.Background()

    // Setup omnillm for LLM-based metrics
    llmClient, _ := omnillm.NewClient(omnillm.ClientConfig{
        Provider: omnillm.ProviderNameOpenAI,
        APIKey:   os.Getenv("OPENAI_API_KEY"),
    })
    defer llmClient.Close()
    llm := metrics.NewLLM(llmClient, "gpt-4o")

    // Setup Phoenix client
    phoenixClient, _ := phoenix.NewClient()

    // Create evaluator
    evaluator := evals.NewEvaluator(phoenixClient)

    // Run evaluation with metrics
    result, _ := evaluator.Evaluate(ctx, llmops.EvalInput{
        Input:   "What is the capital of France?",
        Output:  "The capital of France is London.",
        Context: []string{"Paris is the capital of France."},
        SpanID:  "your-span-id", // Optional: records results to Phoenix
    },
        metrics.NewHallucinationMetric(llm), // LLM-based
        metrics.NewExactMatchMetric(),       // Code-based
    )

    // result.Scores contains evaluation results
    for _, score := range result.Scores {
        fmt.Printf("%s: %.2f\n", score.Name, score.Score)
    }
}

Available Metrics:

Metric Type Description
HallucinationMetric LLM Detects unsupported claims
RelevanceMetric LLM Evaluates document relevance
QACorrectnessMetric LLM Checks answer correctness
ToxicityMetric LLM Detects harmful content
ExactMatchMetric Code Exact string comparison
RegexMetric Code Regex pattern matching
ContainsMetric Code Substring presence check

Environment Variables

Variable Description
PHOENIX_COLLECTOR_ENDPOINT Phoenix collector endpoint (defaults to Phoenix Cloud when PHOENIX_SPACE_ID is set)
PHOENIX_SPACE_ID Space identifier for Phoenix Cloud (e.g., "johncwang" from app.phoenix.arize.com/s/johncwang)
PHOENIX_PROJECT_NAME Project name for traces
PHOENIX_API_KEY API key for authentication
PHOENIX_CLIENT_HEADERS Additional headers (W3C Baggage format)
OTEL_EXPORTER_OTLP_ENDPOINT Fallback OTLP endpoint

Feature Parity with Python SDK

The sections below are ordered by typical usage: start with phoenix-otel to send traces, use phoenix-client to manage resources, then add phoenix-evals to evaluate outputs. These can be used independently—users may adopt any subset based on their needs.

Feature Python SDK go-phoenix Status
phoenix-otel
Register tracer provider Parity
OTLP HTTP exporter Parity
OpenInference attributes Parity
Environment variables Parity
Batch processing Parity
phoenix-client (REST API)
Projects Parity
Spans Parity
Datasets Parity
Experiments Parity
Prompts Parity
Annotations Parity
Sessions Parity
phoenix-evals
LLM evaluators Parity
Hallucination detection Parity
Relevance scoring Parity
Q&A correctness Parity
Toxicity detection Parity
Exact match Parity
Regex matching Parity
Custom templates Parity
Auto-instrumentation
OpenAI auto-instrument N/A (Go limitation)
Anthropic auto-instrument N/A (Go limitation)

OpenInference Span Kinds

The otel package provides constants for OpenInference span kinds:

  • SpanKindLLM - LLM inference calls
  • SpanKindChain - Chain/workflow operations
  • SpanKindTool - Tool/function calls
  • SpanKindAgent - Agent operations
  • SpanKindRetriever - Document retrieval
  • SpanKindEmbedding - Embedding generation
  • SpanKindReranker - Reranking operations
  • SpanKindGuardrail - Guardrail checks

Integration with omniobserve

go-phoenix can be used as a provider for omniobserve:

import (
    "github.com/agentplexus/omniobserve/llmops"
    _ "github.com/agentplexus/go-phoenix/llmops" // Register provider
)

func main() {
    provider, err := llmops.Open("phoenix",
        llmops.WithEndpoint("http://localhost:6006"),
    )
    // ...
}
Feature Comparison
Feature Phoenix (Python) go-phoenix omniobserve/llmops Tests Notes
Tracing
StartTrace Via phoenix-otel
StartSpan Via phoenix-otel
SetInput/Output OpenInference attributes
SetModel/Provider OpenInference attributes
SetUsage (tokens) OpenInference attributes
AddFeedbackScore Via OTEL events
TraceFromContext
SpanFromContext
Nested Spans
Span Types general, llm, tool, retrieval, agent, chain
Duration/Timing
Prompts
CreatePrompt Use WithPromptModel/WithPromptProvider
GetPromptLatest
GetPromptVersion Via GetPrompt(name, versionID)
GetPromptByTag Via GetPrompt(name, tagName)
ListPromptVersions
ListPrompts
Datasets
CreateDataset
GetDataset By name
GetDatasetById
AddDatasetItems
ListDatasets
DeleteDataset
Experiments
CreateExperiment Not in omniobserve interface
RunExperiment Not in omniobserve interface
ListExperiments Not in omniobserve interface
Projects
CreateProject
GetProject
ListProjects
SetProject
Evaluation
Evaluate Run metrics
AddFeedbackScore Record results
Annotations
CreateAnnotation
ListAnnotations

Running omniobserve/llmops tests:

# Skip tests when no API key is set
go test -v ./llmops/

# Run tests with Phoenix Cloud
export PHOENIX_API_KEY=your-api-key
export PHOENIX_SPACE_ID=your-space-id
go test -v ./llmops/

License

MIT License - see LICENSE for details.

Documentation

Overview

Package phoenix provides a Go client for the Arize Phoenix API.

Phoenix is an open-source AI observability platform for experimentation, evaluation, and troubleshooting of LLM applications.

The client wraps the ogen-generated API client with a higher-level interface that handles authentication and provides convenient methods for common operations.

Index

Constants

View Source
const (
	// DefaultURL is the default Phoenix API URL for local instances.
	DefaultURL = "http://localhost:6006"

	// DefaultProjectName is the default project name.
	DefaultProjectName = "default"
)
View Source
const (
	EnvURL         = "PHOENIX_URL"
	EnvAPIKey      = "PHOENIX_API_KEY" //nolint:gosec // G101: This is an environment variable name, not a credential
	EnvProjectName = "PHOENIX_PROJECT_NAME"
	EnvSpaceID     = "PHOENIX_SPACE_ID"
)

Environment variable names.

View Source
const Version = "0.1.0"

Version is the SDK version.

Variables

View Source
var (
	// ErrMissingURL is returned when the API URL is not configured.
	ErrMissingURL = errors.New("phoenix: missing API URL")

	// ErrMissingAPIKey is returned when the API key is required but not provided.
	ErrMissingAPIKey = errors.New("phoenix: missing API key")

	// ErrProjectNotFound is returned when a project cannot be found.
	ErrProjectNotFound = errors.New("phoenix: project not found")

	// ErrTraceNotFound is returned when a trace cannot be found.
	ErrTraceNotFound = errors.New("phoenix: trace not found")

	// ErrSpanNotFound is returned when a span cannot be found.
	ErrSpanNotFound = errors.New("phoenix: span not found")

	// ErrDatasetNotFound is returned when a dataset cannot be found.
	ErrDatasetNotFound = errors.New("phoenix: dataset not found")

	// ErrExperimentNotFound is returned when an experiment cannot be found.
	ErrExperimentNotFound = errors.New("phoenix: experiment not found")

	// ErrPromptNotFound is returned when a prompt cannot be found.
	ErrPromptNotFound = errors.New("phoenix: prompt not found")

	// ErrInvalidInput is returned when input validation fails.
	ErrInvalidInput = errors.New("phoenix: invalid input")
)

Sentinel errors for the Phoenix SDK.

Functions

func IsForbidden

func IsForbidden(err error) bool

IsForbidden returns true if the error indicates access is forbidden.

func IsNotFound

func IsNotFound(err error) bool

IsNotFound returns true if the error indicates a resource was not found.

func IsRateLimited

func IsRateLimited(err error) bool

IsRateLimited returns true if the error indicates rate limiting.

func IsUnauthorized

func IsUnauthorized(err error) bool

IsUnauthorized returns true if the error indicates an authentication failure.

Types

type APIError

type APIError struct {
	StatusCode int
	Message    string
	Details    string
}

APIError represents an error returned by the Phoenix API.

func (*APIError) Error

func (e *APIError) Error() string

type Annotation

type Annotation struct {
	ID          string
	SpanID      string // Set for span annotations
	TraceID     string // Set for trace annotations
	Name        string
	Score       float64
	Label       string
	Explanation string
	Source      AnnotatorKind
	CreatedAt   time.Time
	UpdatedAt   time.Time
}

Annotation represents a Phoenix annotation on a span or trace.

type AnnotationOption

type AnnotationOption func(*annotationOptions)

AnnotationOption configures annotation creation.

func WithAnnotationExplanation

func WithAnnotationExplanation(explanation string) AnnotationOption

WithAnnotationExplanation sets the explanation for the annotation.

func WithAnnotationLabel

func WithAnnotationLabel(label string) AnnotationOption

WithAnnotationLabel sets the label for the annotation.

func WithAnnotationSource

func WithAnnotationSource(source AnnotatorKind) AnnotationOption

WithAnnotationSource sets the source (annotator kind) for the annotation.

type AnnotatorKind

type AnnotatorKind string

AnnotatorKind indicates who created the annotation.

const (
	AnnotatorKindHuman AnnotatorKind = "HUMAN"
	AnnotatorKindLLM   AnnotatorKind = "LLM"
	AnnotatorKindCode  AnnotatorKind = "CODE"
)

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the main Phoenix client for interacting with the API.

func NewClient

func NewClient(opts ...Option) (*Client, error)

NewClient creates a new Phoenix client with the given options.

func (*Client) API

func (c *Client) API() *api.Client

API returns the underlying ogen-generated API client for advanced usage. Use this when you need access to API endpoints not covered by the high-level wrapper methods.

func (*Client) AddDatasetExamples

func (c *Client) AddDatasetExamples(ctx context.Context, datasetName string, examples []DatasetExample) error

AddDatasetExamples appends examples to an existing dataset.

func (*Client) Config

func (c *Client) Config() *Config

Config returns the client configuration.

func (*Client) CreateChatPrompt

func (c *Client) CreateChatPrompt(ctx context.Context, name string, messages []PromptMessage, modelName string, modelProvider PromptModelProvider, opts ...PromptOption) (*PromptVersion, error)

CreateChatPrompt creates a new chat-style prompt with messages.

func (*Client) CreateDataset

func (c *Client) CreateDataset(ctx context.Context, name string, examples []DatasetExample, opts ...DatasetOption) (*Dataset, error)

CreateDataset creates a new dataset with the given examples.

func (*Client) CreateProject

func (c *Client) CreateProject(ctx context.Context, name string, opts ...ProjectOption) (*Project, error)

CreateProject creates a new project.

func (*Client) CreatePrompt

func (c *Client) CreatePrompt(ctx context.Context, name string, template string, modelName string, modelProvider PromptModelProvider, opts ...PromptOption) (*PromptVersion, error)

CreatePrompt creates a new prompt with the given template.

func (*Client) CreateSpanAnnotation

func (c *Client) CreateSpanAnnotation(ctx context.Context, spanID, name string, score float64, opts ...AnnotationOption) error

CreateSpanAnnotation creates an annotation on a span.

func (*Client) CreateTraceAnnotation

func (c *Client) CreateTraceAnnotation(ctx context.Context, traceID, name string, score float64, opts ...AnnotationOption) error

CreateTraceAnnotation creates an annotation on a trace.

func (*Client) DeleteDataset

func (c *Client) DeleteDataset(ctx context.Context, id string) error

DeleteDataset deletes a dataset by ID.

func (*Client) DeleteExperiment

func (c *Client) DeleteExperiment(ctx context.Context, experimentID string) error

DeleteExperiment deletes an experiment.

func (*Client) DeleteProject

func (c *Client) DeleteProject(ctx context.Context, identifier string) error

DeleteProject deletes a project by identifier.

func (*Client) DeleteSpan

func (c *Client) DeleteSpan(ctx context.Context, spanIdentifier string) error

DeleteSpan deletes a span.

func (*Client) DeleteTrace

func (c *Client) DeleteTrace(ctx context.Context, traceIdentifier string) error

DeleteTrace deletes a trace.

func (*Client) GetDataset

func (c *Client) GetDataset(ctx context.Context, id string) (*Dataset, error)

GetDataset retrieves a dataset by ID.

func (*Client) GetProject

func (c *Client) GetProject(ctx context.Context, identifier string) (*Project, error)

GetProject retrieves a project by identifier (ID or name).

func (*Client) GetPromptLatest

func (c *Client) GetPromptLatest(ctx context.Context, name string) (*PromptVersion, error)

GetPromptLatest retrieves the latest version of a prompt by name.

func (*Client) GetPromptVersion

func (c *Client) GetPromptVersion(ctx context.Context, versionID string) (*PromptVersion, error)

GetPromptVersion retrieves a specific prompt version by its ID.

func (*Client) GetPromptVersionByTag

func (c *Client) GetPromptVersionByTag(ctx context.Context, promptName, tagName string) (*PromptVersion, error)

GetPromptVersionByTag retrieves a prompt version by its tag name.

func (*Client) GetSpans

func (c *Client) GetSpans(ctx context.Context, projectIdentifier string, opts ...SpanOption) ([]*Span, string, error)

GetSpans retrieves spans for a project.

func (*Client) ListDatasets

func (c *Client) ListDatasets(ctx context.Context, opts ...ListOption) ([]*Dataset, string, error)

ListDatasets lists all datasets.

func (*Client) ListExperiments

func (c *Client) ListExperiments(ctx context.Context, datasetID string, opts ...ListOption) ([]*Experiment, string, error)

ListExperiments lists experiments for a dataset.

func (*Client) ListProjects

func (c *Client) ListProjects(ctx context.Context, opts ...ListOption) ([]*Project, string, error)

ListProjects lists all projects.

func (*Client) ListPromptVersions

func (c *Client) ListPromptVersions(ctx context.Context, promptName string, opts ...ListOption) ([]*PromptVersion, string, error)

ListPromptVersions lists all versions of a prompt.

func (*Client) ListPrompts

func (c *Client) ListPrompts(ctx context.Context, opts ...ListOption) ([]*Prompt, string, error)

ListPrompts lists all prompts.

func (*Client) ListSpanAnnotations

func (c *Client) ListSpanAnnotations(ctx context.Context, spanIDs []string) ([]*Annotation, error)

ListSpanAnnotations lists annotations for the given span IDs.

func (*Client) ListTraceAnnotations

func (c *Client) ListTraceAnnotations(ctx context.Context, traceIDs []string) ([]*Annotation, error)

ListTraceAnnotations lists annotations for the given trace IDs.

func (*Client) ProjectName

func (c *Client) ProjectName() string

ProjectName returns the default project name.

func (*Client) SetProjectName

func (c *Client) SetProjectName(name string)

SetProjectName sets the default project name.

type Config

type Config struct {
	// URL is the Phoenix API endpoint URL.
	// Defaults to DefaultURL (http://localhost:6006).
	// For Phoenix Cloud, use https://app.phoenix.arize.com
	URL string

	// SpaceID is the space identifier for Phoenix Cloud.
	// When set, the URL is constructed as {URL}/s/{SpaceID}.
	// Not needed for self-hosted Phoenix instances.
	SpaceID string

	// APIKey is the API key for authentication.
	// Optional for local instances, may be required for hosted instances.
	APIKey string

	// ProjectName is the default project name for operations.
	ProjectName string
}

Config holds the configuration for the Phoenix client.

func LoadConfig

func LoadConfig() *Config

LoadConfig loads configuration from environment variables. Priority order (highest to lowest):

  1. Explicitly set values (via options)
  2. Environment variables
  3. Default values

func NewConfig

func NewConfig() *Config

NewConfig creates a new Config with default values.

func (*Config) BaseURL

func (c *Config) BaseURL() string

BaseURL returns the effective base URL (with space if configured).

func (*Config) Validate

func (c *Config) Validate() error

Validate checks if the configuration is valid.

type Dataset

type Dataset struct {
	ID           string
	Name         string
	Description  string
	ExampleCount int
	CreatedAt    time.Time
	UpdatedAt    time.Time
}

Dataset represents a Phoenix dataset.

type DatasetExample

type DatasetExample struct {
	Input    any            `json:"input,omitempty"`
	Output   any            `json:"output,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

DatasetExample represents an example in a dataset.

type DatasetOption

type DatasetOption func(*datasetOptions)

DatasetOption is a functional option for dataset operations.

func WithDatasetDescription

func WithDatasetDescription(desc string) DatasetOption

WithDatasetDescription sets the dataset description.

type Experiment

type Experiment struct {
	ID                 string
	DatasetID          string
	DatasetVersionID   string
	ProjectName        string
	ExampleCount       int
	SuccessfulRunCount int
	FailedRunCount     int
	MissingRunCount    int
	Repetitions        int
	CreatedAt          time.Time
	UpdatedAt          time.Time
}

Experiment represents a Phoenix experiment.

type ListOption

type ListOption func(*listOptions)

ListOption is a functional option for list operations.

func WithCursor

func WithCursor(cursor string) ListOption

WithCursor sets the pagination cursor.

func WithLimit

func WithLimit(limit int) ListOption

WithLimit sets the maximum number of items to return.

type Option

type Option func(*clientOptions)

Option is a functional option for configuring the Client.

func WithAPIKey

func WithAPIKey(apiKey string) Option

WithAPIKey sets the API key for authentication.

func WithConfig

func WithConfig(config *Config) Option

WithConfig sets the entire configuration.

func WithHTTPClient

func WithHTTPClient(client *http.Client) Option

WithHTTPClient sets a custom HTTP client.

func WithProjectName

func WithProjectName(projectName string) Option

WithProjectName sets the default project name.

func WithSpaceID

func WithSpaceID(spaceID string) Option

WithSpaceID sets the space identifier for Phoenix Cloud. When using Phoenix Cloud (app.phoenix.arize.com), set this to your space ID. The URL will be constructed as {BaseURL}/s/{SpaceID}.

func WithTimeout

func WithTimeout(timeout time.Duration) Option

WithTimeout sets the request timeout.

func WithURL

func WithURL(url string) Option

WithURL sets the API URL.

type Project

type Project struct {
	ID          string
	Name        string
	Description string
	CreatedAt   time.Time
	UpdatedAt   time.Time
}

Project represents a Phoenix project.

type ProjectOption

type ProjectOption func(*projectOptions)

ProjectOption is a functional option for project operations.

func WithDescription

func WithDescription(desc string) ProjectOption

WithDescription sets the project description.

func WithName

func WithName(name string) ProjectOption

WithName sets the project name.

type Prompt

type Prompt struct {
	ID             string
	Name           string
	Description    string
	SourcePromptID string
}

Prompt represents a Phoenix prompt.

type PromptMessage

type PromptMessage struct {
	Role    string
	Content string
}

PromptMessage represents a message in a chat prompt.

type PromptModelProvider

type PromptModelProvider string

PromptModelProvider represents the LLM provider for a prompt.

const (
	PromptModelProviderOpenAI      PromptModelProvider = "OPENAI"
	PromptModelProviderAzureOpenAI PromptModelProvider = "AZURE_OPENAI"
	PromptModelProviderAnthropic   PromptModelProvider = "ANTHROPIC"
	PromptModelProviderGoogle      PromptModelProvider = "GOOGLE"
	PromptModelProviderDeepseek    PromptModelProvider = "DEEPSEEK"
	PromptModelProviderXAI         PromptModelProvider = "XAI"
	PromptModelProviderOllama      PromptModelProvider = "OLLAMA"
	PromptModelProviderAWS         PromptModelProvider = "AWS"
)

type PromptOption

type PromptOption func(*promptOptions)

PromptOption is a functional option for prompt operations.

func WithPromptDescription

func WithPromptDescription(desc string) PromptOption

WithPromptDescription sets the prompt description.

type PromptTemplateType

type PromptTemplateType string

PromptTemplateType represents the type of prompt template.

const (
	PromptTemplateTypeChat   PromptTemplateType = "CHAT"
	PromptTemplateTypeString PromptTemplateType = "STRING"
)

type PromptVersion

type PromptVersion struct {
	ID            string
	Description   string
	Template      string // The prompt template content
	TemplateType  PromptTemplateType
	ModelName     string
	ModelProvider PromptModelProvider
}

PromptVersion represents a version of a prompt.

type Span

type Span struct {
	ID            string
	Name          string
	SpanKind      string
	StatusCode    string
	StatusMessage string
	ParentID      string
	TraceID       string
	SpanID        string
	StartTime     time.Time
	EndTime       time.Time
}

Span represents a Phoenix span.

type SpanOption

type SpanOption func(*spanOptions)

SpanOption is a functional option for span operations.

func WithSpanCursor

func WithSpanCursor(cursor string) SpanOption

WithSpanCursor sets the pagination cursor for spans.

func WithSpanLimit

func WithSpanLimit(limit int) SpanOption

WithSpanLimit sets the max number of spans to return.

Directories

Path Synopsis
cmd
openapi-convert command
Command openapi-convert converts OpenAPI 3.1 specs to 3.0.3 for ogen compatibility.
Command openapi-convert converts OpenAPI 3.1 specs to 3.0.3 for ogen compatibility.
Package evals provides evaluation capabilities for Phoenix.
Package evals provides evaluation capabilities for Phoenix.
internal
api
Code generated by ogen, DO NOT EDIT.
Code generated by ogen, DO NOT EDIT.
Package llmops provides an omniobserve/llmops adapter for go-phoenix.
Package llmops provides an omniobserve/llmops adapter for go-phoenix.
Package otel provides OpenTelemetry integration for Phoenix.
Package otel provides OpenTelemetry integration for Phoenix.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL