ax

package
v0.8.0 Latest Latest
Warning

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

 Go to latest Published: Jun 22, 2026 License: MIT Imports: 1 Imported by: 0

Documentation

Overview

Package ax provides Agent Experience (AX) metadata for the Opik API.

This package is generated by ax-spec from x-ax-* OpenAPI extensions and API discovery. It provides:

  • Error code constants for machine-readable error handling
  • Retry policies indicating which operations are safe to retry
  • Capability mappings for operation introspection
  • Required field validation for request bodies

Error Handling Example: 

import "github.com/plexusone/opik-go/ax"

trace, err := client.GetTrace(ctx, traceID)
if err != nil {
    apiErr := opik.ParseAPIError(err)
    if apiErr != nil && ax.IsErrorCode(apiErr, ax.ErrTraceNotFound) {
        // Handle specific error
    }
}

Retry Policy Example: 

if ax.IsRetryable("findTraces") {
    // Safe to implement automatic retry
}

The Opik API is used for LLM observability, tracing, and evaluation. Machine-readable error codes enable AI agents to reliably integrate with observability pipelines.

Index

Constants

View Source 
const (
	// ErrTraceNotFound indicates the requested trace was not found.
	ErrTraceNotFound = "TRACE_NOT_FOUND"

	// ErrSpanNotFound indicates the requested span was not found.
	ErrSpanNotFound = "SPAN_NOT_FOUND"

	// ErrDatasetNotFound indicates the requested dataset was not found.
	ErrDatasetNotFound = "DATASET_NOT_FOUND"

	// ErrExperimentNotFound indicates the requested experiment was not found.
	ErrExperimentNotFound = "EXPERIMENT_NOT_FOUND"

	// ErrPromptNotFound indicates the requested prompt was not found.
	ErrPromptNotFound = "PROMPT_NOT_FOUND"

	// ErrProjectNotFound indicates the requested project was not found.
	ErrProjectNotFound = "PROJECT_NOT_FOUND"

	// ErrFeedbackNotFound indicates the requested feedback was not found.
	ErrFeedbackNotFound = "FEEDBACK_NOT_FOUND"

	// ErrAttachmentNotFound indicates the requested attachment was not found.
	ErrAttachmentNotFound = "ATTACHMENT_NOT_FOUND"

	// ErrUnauthorized indicates authentication is required or failed.
	ErrUnauthorized = "UNAUTHORIZED"

	// ErrForbidden indicates the user lacks permission for the operation.
	ErrForbidden = "FORBIDDEN"

	// ErrInvalidInput indicates the request input validation failed.
	ErrInvalidInput = "INVALID_INPUT"

	// ErrConflict indicates a resource conflict (e.g., duplicate name).
	ErrConflict = "CONFLICT"

	// ErrRateLimited indicates the request was rate limited.
	ErrRateLimited = "RATE_LIMITED"

	// ErrInternalError indicates an internal server error.
	ErrInternalError = "INTERNAL_ERROR"

	// ErrWorkspaceNotFound indicates the workspace was not found.
	ErrWorkspaceNotFound = "WORKSPACE_NOT_FOUND"

	// ErrEvaluatorNotFound indicates the evaluator was not found.
	ErrEvaluatorNotFound = "EVALUATOR_NOT_FOUND"

	// ErrAlertNotFound indicates the alert was not found.
	ErrAlertNotFound = "ALERT_NOT_FOUND"

	// ErrQueueNotFound indicates the annotation queue was not found.
	ErrQueueNotFound = "QUEUE_NOT_FOUND"

	// ErrDashboardNotFound indicates the dashboard was not found.
	ErrDashboardNotFound = "DASHBOARD_NOT_FOUND"
)

Error codes for the Opik API. These codes enable machine-readable error handling for AI agents working with LLM observability and tracing.

Variables

View Source 
var AllErrorCodes = []string{
	ErrTraceNotFound,
	ErrSpanNotFound,
	ErrDatasetNotFound,
	ErrExperimentNotFound,
	ErrPromptNotFound,
	ErrProjectNotFound,
	ErrFeedbackNotFound,
	ErrAttachmentNotFound,
	ErrUnauthorized,
	ErrForbidden,
	ErrInvalidInput,
	ErrConflict,
	ErrRateLimited,
	ErrInternalError,
	ErrWorkspaceNotFound,
	ErrEvaluatorNotFound,
	ErrAlertNotFound,
	ErrQueueNotFound,
	ErrDashboardNotFound,
}

AllErrorCodes contains all known Opik API error codes.

View Source 
var ErrorCodeMetadata = map[string]ErrorCodeInfo{
	ErrTraceNotFound: {
		Code:        ErrTraceNotFound,
		Description: "The requested trace was not found",
		Retryable:   false,
		Category:    "not_found",
		HTTPStatus:  404,
	},
	ErrSpanNotFound: {
		Code:        ErrSpanNotFound,
		Description: "The requested span was not found",
		Retryable:   false,
		Category:    "not_found",
		HTTPStatus:  404,
	},
	ErrDatasetNotFound: {
		Code:        ErrDatasetNotFound,
		Description: "The requested dataset was not found",
		Retryable:   false,
		Category:    "not_found",
		HTTPStatus:  404,
	},
	ErrExperimentNotFound: {
		Code:        ErrExperimentNotFound,
		Description: "The requested experiment was not found",
		Retryable:   false,
		Category:    "not_found",
		HTTPStatus:  404,
	},
	ErrPromptNotFound: {
		Code:        ErrPromptNotFound,
		Description: "The requested prompt was not found",
		Retryable:   false,
		Category:    "not_found",
		HTTPStatus:  404,
	},
	ErrProjectNotFound: {
		Code:        ErrProjectNotFound,
		Description: "The requested project was not found",
		Retryable:   false,
		Category:    "not_found",
		HTTPStatus:  404,
	},
	ErrFeedbackNotFound: {
		Code:        ErrFeedbackNotFound,
		Description: "The requested feedback was not found",
		Retryable:   false,
		Category:    "not_found",
		HTTPStatus:  404,
	},
	ErrAttachmentNotFound: {
		Code:        ErrAttachmentNotFound,
		Description: "The requested attachment was not found",
		Retryable:   false,
		Category:    "not_found",
		HTTPStatus:  404,
	},
	ErrUnauthorized: {
		Code:        ErrUnauthorized,
		Description: "Authentication is required or failed",
		Retryable:   false,
		Category:    "auth",
		HTTPStatus:  401,
	},
	ErrForbidden: {
		Code:        ErrForbidden,
		Description: "User lacks permission for this operation",
		Retryable:   false,
		Category:    "auth",
		HTTPStatus:  403,
	},
	ErrInvalidInput: {
		Code:        ErrInvalidInput,
		Description: "Request input validation failed",
		Retryable:   false,
		Category:    "validation",
		HTTPStatus:  400,
	},
	ErrConflict: {
		Code:        ErrConflict,
		Description: "Resource conflict (e.g., duplicate name)",
		Retryable:   false,
		Category:    "conflict",
		HTTPStatus:  409,
	},
	ErrRateLimited: {
		Code:        ErrRateLimited,
		Description: "Request was rate limited",
		Retryable:   true,
		Category:    "rate_limit",
		HTTPStatus:  429,
	},
	ErrInternalError: {
		Code:        ErrInternalError,
		Description: "Internal server error",
		Retryable:   true,
		Category:    "server",
		HTTPStatus:  500,
	},
	ErrWorkspaceNotFound: {
		Code:        ErrWorkspaceNotFound,
		Description: "The workspace was not found",
		Retryable:   false,
		Category:    "not_found",
		HTTPStatus:  404,
	},
	ErrEvaluatorNotFound: {
		Code:        ErrEvaluatorNotFound,
		Description: "The evaluator was not found",
		Retryable:   false,
		Category:    "not_found",
		HTTPStatus:  404,
	},
	ErrAlertNotFound: {
		Code:        ErrAlertNotFound,
		Description: "The alert was not found",
		Retryable:   false,
		Category:    "not_found",
		HTTPStatus:  404,
	},
	ErrQueueNotFound: {
		Code:        ErrQueueNotFound,
		Description: "The annotation queue was not found",
		Retryable:   false,
		Category:    "not_found",
		HTTPStatus:  404,
	},
	ErrDashboardNotFound: {
		Code:        ErrDashboardNotFound,
		Description: "The dashboard was not found",
		Retryable:   false,
		Category:    "not_found",
		HTTPStatus:  404,
	},
}

ErrorCodeMetadata maps error codes to their metadata.

View Source 
var OperationCapabilities = map[string][]Capability{

	"getDatasetBiInfo":            {CapRead, CapAnalytics},
	"getExperimentBiInfo":         {CapRead, CapAnalytics},
	"getSpansBiInfo":              {CapRead, CapAnalytics},
	"getSpansCountForWorkspaces":  {CapRead, CapAnalytics},
	"getTracesBiInfo":             {CapRead, CapAnalytics},
	"getTracesCountForWorkspaces": {CapRead, CapAnalytics},

	"findTraces":         {CapRead},
	"getTracesByProject": {CapRead},
	"createTrace":        {CapWrite},
	"createTraces":       {CapWrite},
	"getTraceById":       {CapRead},
	"updateTrace":        {CapWrite},
	"deleteTraceById":    {CapWrite, CapDelete},
	"deleteTraces":       {CapWrite, CapDelete},
	"searchTraces":       {CapRead},
	"getTraceStats":      {CapRead, CapAnalytics},

	"getSpansByProject": {CapRead},
	"createSpan":        {CapWrite},
	"createSpans":       {CapWrite},
	"getSpanById":       {CapRead},
	"updateSpan":        {CapWrite},
	"deleteSpanById":    {CapWrite, CapDelete},
	"searchSpans":       {CapRead},
	"getSpanStats":      {CapRead, CapAnalytics},

	"findDatasets":        {CapRead},
	"createDataset":       {CapWrite},
	"getDatasetById":      {CapRead},
	"updateDataset":       {CapWrite},
	"deleteDataset":       {CapWrite, CapDelete},
	"deleteDatasetsBatch": {CapWrite, CapDelete},
	"getDatasetItems":     {CapRead},
	"streamDatasetItems":  {CapRead, CapStream},

	"findExperiments":       {CapRead},
	"createExperiment":      {CapWrite},
	"getExperimentById":     {CapRead},
	"updateExperiment":      {CapWrite},
	"deleteExperimentsById": {CapWrite, CapDelete},
	"streamExperimentItems": {CapRead, CapStream},
	"streamExperiments":     {CapRead, CapStream},

	"findProjects":        {CapRead},
	"createProject":       {CapWrite},
	"getProjectById":      {CapRead},
	"updateProject":       {CapWrite},
	"deleteProjectById":   {CapWrite, CapDelete},
	"deleteProjectsBatch": {CapWrite, CapDelete},
	"getProjectMetrics":   {CapRead, CapAnalytics},
	"getProjectStats":     {CapRead, CapAnalytics},

	"getPrompts":           {CapRead},
	"createPrompt":         {CapWrite},
	"getPromptById":        {CapRead},
	"updatePrompt":         {CapWrite},
	"deletePrompt":         {CapWrite, CapDelete},
	"getPromptVersions":    {CapRead},
	"createPromptVersion":  {CapWrite},
	"getPromptVersionById": {CapRead},

	"evaluateSpans":   {CapWrite, CapEvaluate},
	"evaluateThreads": {CapWrite, CapEvaluate},
	"evaluateTraces":  {CapWrite, CapEvaluate},

	"findEvaluators":                     {CapRead},
	"createAutomationRuleEvaluator":      {CapWrite},
	"getEvaluatorById":                   {CapRead},
	"updateAutomationRuleEvaluator":      {CapWrite},
	"deleteAutomationRuleEvaluatorBatch": {CapWrite, CapDelete},

	"findFeedbackDefinitions":      {CapRead},
	"createFeedbackDefinition":     {CapWrite},
	"getFeedbackDefinitionById":    {CapRead},
	"updateFeedbackDefinition":     {CapWrite},
	"deleteFeedbackDefinitionById": {CapWrite, CapDelete},
	"addSpanFeedbackScore":         {CapWrite},
	"addTraceFeedbackScore":        {CapWrite},

	"findDashboards":   {CapRead},
	"createDashboard":  {CapWrite},
	"getDashboardById": {CapRead},
	"updateDashboard":  {CapWrite},
	"deleteDashboard":  {CapWrite, CapDelete},

	"findAlerts":       {CapRead},
	"createAlert":      {CapWrite},
	"getAlertById":     {CapRead},
	"updateAlert":      {CapWrite},
	"deleteAlertBatch": {CapWrite, CapDelete},

	"attachmentList":     {CapRead},
	"downloadAttachment": {CapRead},
	"uploadAttachment":   {CapWrite},
	"deleteAttachments":  {CapWrite, CapDelete},

	"costsSummary":   {CapRead, CapAnalytics},
	"getCost":        {CapRead, CapAnalytics},
	"getMetric":      {CapRead, CapAnalytics},
	"metricsSummary": {CapRead, CapAnalytics},

	"getWorkspaceConfiguration":     {CapRead, CapAdmin},
	"upsertWorkspaceConfiguration":  {CapWrite, CapAdmin},
	"deleteWorkspaceConfiguration":  {CapWrite, CapDelete, CapAdmin},
	"storeLlmProviderApiKey":        {CapWrite, CapAdmin},
	"updateLlmProviderApiKey":       {CapWrite, CapAdmin},
	"deleteLlmProviderApiKeysBatch": {CapWrite, CapDelete, CapAdmin},

	"isAlive": {CapRead},
	"version": {CapRead},
}

OperationCapabilities maps operation IDs to their capabilities. Capabilities indicate what an operation can do:

  • read: retrieves data without modification
  • write: creates or modifies data
  • delete: removes data
  • admin: administrative operations requiring elevated permissions
  • stream: supports streaming responses
  • evaluate: performs LLM evaluation
  • analytics: retrieves analytics/metrics data
View Source 
var RequiredFields = map[string][]string{

	"createAlert": {"name", "notification"},
	"updateAlert": {"name", "notification"},

	"createAnnotationQueue":      {"name"},
	"createAnnotationQueueBatch": {"queues"},
	"updateAnnotationQueue":      {"name"},

	"completeMultiPartUpload": {"file_name", "entity_type", "entity_id", "num_uploaded_parts"},
	"startMultiPartUpload":    {"file_name", "entity_type", "entity_id", "num_parts"},
	"uploadAttachment":        {"file", "entity_type", "entity_id"},

	"createAutomationRuleEvaluator": {"name", "code"},
	"updateAutomationRuleEvaluator": {"name", "code"},

	"createChatCompletions": {"model", "messages"},

	"createDashboard": {"name"},
	"updateDashboard": {"name"},

	"createDataset":                {"name"},
	"createOrUpdateDatasetItems":   {"items"},
	"createDatasetItemsFromCsv":    {"file"},
	"createDatasetItemsFromSpans":  {"span_ids"},
	"createDatasetItemsFromTraces": {"trace_ids"},
	"updateDataset":                {"name"},
	"createVersionTag":             {"tag_name"},
	"createDatasetVersion":         {"name"},
	"updateDatasetVersion":         {"name"},

	"createExperiment":      {"dataset_name", "name"},
	"createExperimentItems": {"experiment_items"},
	"experimentItemsBulk":   {"experiment_items"},
	"updateExperiment":      {"name"},

	"createFeedbackDefinition": {"name", "type"},
	"updateFeedbackDefinition": {"name", "type"},

	"createGuardrails": {"project_name", "trace_id", "span_id"},

	"storeLlmProviderApiKey":  {"provider", "api_key"},
	"updateLlmProviderApiKey": {"api_key"},

	"evaluateSpans":   {"span_ids", "evaluator_ids"},
	"evaluateThreads": {"thread_ids", "evaluator_ids"},
	"evaluateTraces":  {"trace_ids", "evaluator_ids"},

	"createOptimization": {"project_name", "name"},
	"upsertOptimization": {"project_name", "name"},

	"createProject": {"name"},
	"updateProject": {"name"},

	"createPrompt":        {"name", "template"},
	"createPromptVersion": {"template"},
	"updatePrompt":        {"name"},

	"addSpanComment":       {"text"},
	"addSpanFeedbackScore": {"name", "value"},
	"createSpans":          {"spans"},
	"createSpan":           {"trace_id", "name"},
	"updateSpan":           {"trace_id"},
	"updateSpanComment":    {"text"},

	"addThreadComment":    {"text"},
	"updateThread":        {"name"},
	"updateThreadComment": {"text"},

	"addTraceComment":       {"text"},
	"addTraceFeedbackScore": {"name", "value"},
	"createTraces":          {"traces"},
	"createTrace":           {"name"},
	"updateTrace":           {"project_name"},
	"updateTraceComment":    {"text"},

	"upsertWorkspaceConfiguration": {"config"},

	"searchSpans":        {"filters"},
	"searchTraces":       {"filters"},
	"searchTraceThreads": {"filters"},
}

RequiredFields maps operation IDs to their required input fields. This is extracted from the OpenAPI specification's requestBody schema required fields, allowing pre-flight validation before making API calls.

View Source 
var RetryPolicy = map[string]bool{}/* 201 elements not displayed */

RetryPolicy maps operation IDs to their retry safety. true = safe to retry automatically (idempotent reads) false = not safe to retry without user confirmation (may cause duplicates)

This information is derived from:

  • HTTP method (GET/HEAD/OPTIONS are generally safe)
  • Operation semantics (create operations are not safe)
  • x-ax-retryable extensions when present

Functions

func ContainsErrorCode 

func ContainsErrorCode(err error) (string, bool)

ContainsErrorCode extracts the AX error code from an error, if present. Returns the matching code and true if found, empty string and false otherwise.

func ErrorCodeForHTTPStatus 

func ErrorCodeForHTTPStatus(status int) string

ErrorCodeForHTTPStatus returns a likely error code for an HTTP status. This is a heuristic when no specific error code is available.

func GetNonRetryableOperations 

func GetNonRetryableOperations() []string

GetNonRetryableOperations returns all operation IDs that are NOT safe to retry.

func GetOperationsByCapability 

func GetOperationsByCapability(cap Capability) []string

GetOperationsByCapability returns all operations that have a specific capability.

func GetRequiredFields 

func GetRequiredFields(operationID string) []string

GetRequiredFields returns the required fields for an operation. Returns nil if the operation has no required fields or is not found.

func GetRetryableOperations 

func GetRetryableOperations() []string

GetRetryableOperations returns all operation IDs that are safe to retry.

func HasCapability 

func HasCapability(operationID string, cap Capability) bool

HasCapability checks if an operation has a specific capability.

func HasRequiredFields 

func HasRequiredFields(operationID string) bool

HasRequiredFields returns true if the operation has required fields.

func IsAuthError 

func IsAuthError(code string) bool

IsAuthError returns true if the error code indicates an authentication/authorization issue.

func IsConflictError 

func IsConflictError(code string) bool

IsConflictError returns true if the error code indicates a resource conflict.

func IsErrorCode 

func IsErrorCode(err error, code string) bool

IsErrorCode checks if an error contains the specified AX error code. It works with any error type by checking if the error string contains the code.

func IsEvaluation 

func IsEvaluation(operationID string) bool

IsEvaluation returns true if an operation is an evaluation operation.

func IsNotFoundError 

func IsNotFoundError(code string) bool

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

func IsReadOnly 

func IsReadOnly(operationID string) bool

IsReadOnly returns true if an operation only has read capability.

func IsRetryable 

func IsRetryable(operationID string) bool

IsRetryable returns whether an operation is safe to retry automatically. Operations not in the map default to false (not retryable).

func IsRetryableError 

func IsRetryableError(code string) bool

IsRetryableError returns true if the error code indicates a retryable error.

func IsValidationError 

func IsValidationError(code string) bool

IsValidationError returns true if the error code indicates a validation failure.

func MissingFields 

func MissingFields(operationID string, presentFields map[string]bool) []string

MissingFields checks which required fields are missing from a request. The provided map should contain the field names that are present. Returns a slice of missing field names.

func RequiresAdmin 

func RequiresAdmin(operationID string) bool

RequiresAdmin returns true if an operation requires admin capability.

func RetryableCount 

func RetryableCount() (retryable, nonRetryable int)

RetryableCount returns counts of retryable and non-retryable operations.

func SupportsStreaming 

func SupportsStreaming(operationID string) bool

SupportsStreaming returns true if an operation supports streaming.

func ValidateFields 

func ValidateFields(operationID string, presentFields map[string]bool) string

ValidateFields returns an error message if required fields are missing. Returns empty string if all required fields are present.

Types

type Capability 

type Capability string

Capability represents an operation capability for agent introspection. 

const (
	CapRead      Capability = "read"
	CapWrite     Capability = "write"
	CapDelete    Capability = "delete"
	CapAdmin     Capability = "admin"
	CapStream    Capability = "stream"
	CapEvaluate  Capability = "evaluate"
	CapAnalytics Capability = "analytics"
)

Standard capabilities derived from operation semantics.

func GetCapabilities 

func GetCapabilities(operationID string) []Capability

GetCapabilities returns the capabilities for an operation. Returns nil if the operation is not found.

type ErrorCodeInfo 

type ErrorCodeInfo struct {
	Code        string
	Description string
	Retryable   bool
	Category    string
	HTTPStatus  int
}

ErrorCodeInfo provides metadata about an error code.

func GetErrorInfo 

func GetErrorInfo(code string) *ErrorCodeInfo

GetErrorInfo returns metadata about an error code. Returns nil if the code is not recognized.

type OperationRequirements 

type OperationRequirements struct {
	OperationID    string
	RequiredFields []string
	Retryable      bool
}

OperationRequirements returns a summary of an operation's requirements.

func GetOperationRequirements 

func GetOperationRequirements(operationID string) *OperationRequirements

GetOperationRequirements returns full requirements for an operation.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.