axiom/dist/feedback.d.ts

Axiom AI SDK provides - an API to wrap your AI calls with observability instrumentation. - offline evals

type FeedbackInputBase = {
    readonly name: string;
    readonly message?: string;
    readonly category?: string;
    readonly metadata?: Record<string, unknown>;
};
type FeedbackCoreNumber = {
    readonly kind: 'number';
    readonly value: number;
};
type FeedbackCoreThumb = {
    readonly kind: 'thumb';
    readonly value: -1 | 1;
};
type FeedbackCoreBoolean = {
    readonly kind: 'boolean';
    readonly value: boolean;
};
type FeedbackCoreText = {
    readonly kind: 'text';
    readonly value: string;
};
type FeedbackCoreSignal = {
    readonly kind: 'signal';
    readonly value: null;
};
/** Feedback with a number value (e.g., similarity, 0-1). */
type FeedbackInputNumber = FeedbackInputBase & FeedbackCoreNumber;
/** Feedback with a thumbs up (+1) or thumbs down (-1) value. */
type FeedbackInputThumb = FeedbackInputBase & FeedbackCoreThumb;
/** Feedback with a boolean value (true/false). */
type FeedbackInputBoolean = FeedbackInputBase & FeedbackCoreBoolean;
/** Feedback with a free-form text value. */
type FeedbackInputText = FeedbackInputBase & FeedbackCoreText;
/** Feedback without a value, used to signal an event occurred. */
type FeedbackInputSignal = FeedbackInputBase & FeedbackCoreSignal;
/** Union of all feedback input types. Discriminated on `kind`. */
type FeedbackInput = FeedbackInputNumber | FeedbackInputThumb | FeedbackInputBoolean | FeedbackInputText | FeedbackInputSignal;
/** Links that associate feedback with a trace and other context. */
type FeedbackLinks = {
    /** The trace ID to associate this feedback with. */
    readonly traceId: string;
    /** The capability (feature/component) this feedback relates to. */
    readonly capability: string;
    /** Optional step within the capability. */
    readonly step?: string;
    /** Optional span ID for more granular linking. */
    readonly spanId?: string;
    /** Optional conversation ID for conversational contexts. */
    readonly conversationId?: string;
    /** Optional user ID of the person providing feedback. */
    readonly userId?: string;
};
type FeedbackLinksSerialized = {
    readonly trace_id: string;
    readonly capability: string;
    readonly step?: string;
    readonly span_id?: string;
    readonly conversation_id?: string;
    readonly userId?: string;
};
type FeedbackEventBase = {
    readonly schemaUrl: string;
    readonly id: string;
    readonly name: string;
    readonly message?: string;
    readonly category?: string;
    readonly metadata?: Record<string, unknown>;
    readonly links: FeedbackLinksSerialized;
    readonly event: 'feedback';
};
type FeedbackEventStoredBase = FeedbackEventBase & {
    readonly _time: string;
};
type FeedbackEventNumber = FeedbackEventStoredBase & FeedbackCoreNumber;
type FeedbackEventThumb = FeedbackEventStoredBase & FeedbackCoreThumb;
type FeedbackEventBoolean = FeedbackEventStoredBase & FeedbackCoreBoolean;
type FeedbackEventText = FeedbackEventStoredBase & FeedbackCoreText;
type FeedbackEventSignal = FeedbackEventStoredBase & FeedbackCoreSignal;
/** Union of all feedback event types as returned from Axiom queries. Discriminated on `kind`. */
type FeedbackEvent = FeedbackEventNumber | FeedbackEventThumb | FeedbackEventBoolean | FeedbackEventText | FeedbackEventSignal;
/** Parameters for creating a number feedback (excludes `kind`). */
type FeedbackParamsNumber = Omit<FeedbackInputNumber, 'kind'>;
/** Parameters for creating a thumb feedback (excludes `kind`). */
/** Parameters for creating a boolean feedback (excludes `kind`). */
type FeedbackParamsBoolean = Omit<FeedbackInputBoolean, 'kind'>;
/** Parameters for creating a text feedback (excludes `kind`). */
type FeedbackParamsText = Omit<FeedbackInputText, 'kind'>;
/** Parameters for creating a signal feedback (excludes `kind` and `value`). */
type FeedbackParamsSignal = Omit<FeedbackInputSignal, 'kind' | 'value'>;
/** Base parameters shared by all feedback types (name, message, category, metadata). */
type FeedbackParamsBase = FeedbackInputBase;
/** Configuration for connecting to the Axiom feedback API. */
type FeedbackConfig = {
    /** Axiom API token with ingest permissions. */
    readonly token: string;
    /** Axiom dataset to send feedback to. */
    readonly dataset: string;
    /** Optional custom Axiom API URL. Defaults to https://api.axiom.co. */
    readonly url?: string;
};
type FeedbackErrorContext = {
    readonly links: FeedbackLinks;
    readonly feedback: FeedbackInput;
};
type FeedbackSettings = {
    readonly onError?: (error: Error, context: FeedbackErrorContext) => void;
};
/** Function signature for sending feedback. */
type SendFeedbackFn = (links: FeedbackLinks, feedback: FeedbackInput) => Promise<void>;
/** Client for sending feedback to Axiom. */
type FeedbackClient = {
    /** Sends feedback associated with the given links. */
    readonly sendFeedback: SendFeedbackFn;
};
/**
 * Creates a feedback client for sending user feedback to Axiom.
 *
 * @example
 * ```ts
 * const client = createFeedbackClient({ token: 'xaat-...', dataset: 'feedback' });
 * void client.sendFeedback(
 *   { traceId: '...', capability: 'support-agent' },
 *   Feedback.thumbUp({ name: 'response-quality' })
 * );
 * ```
 */
declare const createFeedbackClient: (config: FeedbackConfig, settings?: FeedbackSettings) => FeedbackClient;
/**
 * Helper functions for creating feedback input objects.
 *
 * @example
 * ```ts
 * Feedback.thumbUp({ name: 'response-quality' })
 * Feedback.number({ name: 'rating', value: 4 })
 * Feedback.signal({ name: 'completed' })
 * ```
 */
declare const Feedback: {
    /** Creates a signal feedback (no value, just indicates an event occurred). */
    signal: (input: FeedbackParamsSignal) => FeedbackInputSignal;
    /** Creates a number feedback with a number value. */
    number: (input: FeedbackParamsNumber) => FeedbackInputNumber;
    /** Creates a boolean feedback with a true/false value. */
    bool: (input: FeedbackParamsBoolean) => FeedbackInputBoolean;
    /** Creates a text feedback with a free-form string value. */
    text: (input: FeedbackParamsText) => FeedbackInputText;
    /** Creates a text feedback from a string enum value. */
    enum: <T extends string>(input: FeedbackParamsBase & {
        readonly value: T;
    }) => FeedbackInputText;
    /** Creates a thumb feedback with 'up' or 'down' value. */
    thumb: ({ name, value, message, category, metadata, }: FeedbackParamsBase & {
        readonly value: "up" | "down";
    }) => FeedbackInputThumb;
    /** Creates a thumbs up (+1) feedback. */
    thumbUp: (input: FeedbackParamsBase) => FeedbackInputThumb;
    /** Creates a thumbs down (-1) feedback. */
    thumbDown: (input: FeedbackParamsBase) => FeedbackInputThumb;
};

export { Feedback, type FeedbackClient, type FeedbackConfig, type FeedbackErrorContext, type FeedbackEvent, type FeedbackInput, type FeedbackLinks, type FeedbackSettings, type SendFeedbackFn, createFeedbackClient };