axiom
Version:
Axiom AI SDK provides - an API to wrap your AI calls with observability instrumentation. - offline evals - online evals
207 lines (204 loc) • 6.49 kB
TypeScript
import { TracerProvider } from '@opentelemetry/api';
import { z } from 'zod';
/**
* Utility type to make all properties in T required recursively.
* Keeps the types as-is but removes the optionality.
*/
type DeepRequired<T> = T extends Array<infer U> ? Array<U> : T extends (...args: any[]) => any ? T : T extends object ? {
[P in keyof T]-?: DeepRequired<T[P]>;
} : T;
/**
* Axiom API connection configuration
*/
interface AxiomConnectionConfig {
/**
* Axiom API URL
* @default 'https://api.axiom.co'
* @example 'https://api.axiom.co'
*/
url?: string;
/**
* Axiom Edge URL for ingest and query operations.
* When set, this URL is used for sending traces and querying data,
* while the regular `url` is used for API/console operations.
* Falls back to `url` if not specified.
* @example 'https://eu-central-1.aws.edge.axiom.co'
*/
edgeUrl?: string;
/**
* Axiom API token (can be undefined if not set)
* @example process.env.AXIOM_TOKEN
*/
token?: string | undefined;
/**
* Axiom dataset name
* @example process.env.AXIOM_DATASET
*/
dataset?: string;
/**
* Axiom organization ID
* @example process.env.AXIOM_ORG_ID
*/
orgId?: string;
}
/**
* Options passed to the instrumentation hook
* - url: string
* - token: string
* - dataset: string
*/
interface AxiomEvalInstrumentationOptions {
url: string;
edgeUrl: string;
token: string;
dataset: string;
orgId?: string;
}
/**
* Result returned from the instrumentation hook
*/
interface AxiomEvalInstrumentationResult {
/**
* TracerProvider to be flushed when eval finishes.
*
* If you use the NodeSDK or register your provider globally, you don't need to return it
* here as the NodeSDK automatically flushes the global provider.
*
* Only return a provider if you want Axiom to explicitly flush it for you and it's not
* registered as the global tracer provider.
*/
provider?: TracerProvider;
}
/**
* Hook function to initialize application OpenTelemetry instrumentation.
* Called before eval execution with resolved Axiom connection details.
*
* @param options - Configuration options
* @param options.url - Axiom API URL
* @param options.token - Axiom API token
* @param options.dataset - Axiom dataset name
* @returns TracerProvider or Promise resolving to TracerProvider
*
* @example
* ```typescript
* instrumentation: ({ url, token, dataset }) => {
* return setupAppInstrumentation({ url, token, dataset });
* }
* ```
*/
type AxiomEvalInstrumentationHook = (options: AxiomEvalInstrumentationOptions) => AxiomEvalInstrumentationResult | Promise<AxiomEvalInstrumentationResult>;
interface AxiomConfigBase {
/**
* Eval configuration settings
*
* @example
* ```typescript
* eval: {
* url: process.env.AXIOM_URL,
* token: process.env.AXIOM_TOKEN,
* dataset: process.env.AXIOM_DATASET
* }
* ```
*/
eval?: AxiomConnectionConfig & {
/**
* Zod schema for flag validation.
* When provided, CLI flags (--flag.*) are validated against this schema
* before eval execution begins.
*
* @example
* ```typescript
* import { z } from 'zod';
*
* export default defineConfig({
* eval: {
* flagSchema: z.object({
* model: z.object({
* temperature: z.number().min(0).max(2).default(0.7),
* name: z.string().default('gpt-4o'),
* }),
* }),
* }
* });
* ```
*/
flagSchema?: z.ZodObject<any> | null;
/**
* Optional hook to initialize application OpenTelemetry instrumentation.
* Called before eval execution with resolved Axiom connection details.
* Return your configured tracer provider/tracer (or void) after registering them.
*/
instrumentation?: AxiomEvalInstrumentationHook | null;
/**
* Timeout for eval execution in milliseconds
* @default 60000
*/
timeoutMs?: number;
/**
* Glob patterns to include when running evals
* @default ['**\/*.eval.{ts,js,mts,mjs,cts,cjs}']
* @example ['**\/*.eval.ts', 'tests/**\/*.test.ts']
*/
include?: string[];
/**
* Glob patterns to exclude when running evals
* @default ['**\/node_modules/**', '**\/dist/**', '**\/build/**']
* @example ['**\/node_modules/**', '**\/.next/**']
*/
exclude?: string[];
};
}
/**
* Resolved Axiom AI SDK configuration with all required keys.
* This is the type returned after merging user config with defaults.
*
* Uses DeepRequired to ensure all optional properties from AxiomConfigBase
* become required, preventing missing properties in the resolved config.
*/
type ResolvedAxiomConfig = DeepRequired<AxiomConfigBase>;
/**
* Axiom AI SDK configuration with optional environment-specific overrides.
*
* Supports c12 environment overrides using $development, $production, etc.
*
* @example
* ```typescript
* export default defineConfig({
* eval: {
* url: process.env.AXIOM_URL,
* token: process.env.AXIOM_TOKEN,
* dataset: process.env.AXIOM_DATASET,
* },
* })
* ```
*/
interface AxiomConfig extends AxiomConfigBase {
/**
* Allow c12 environment-specific overrides ($development, $production, $test etc.)
* but don't show them in autocomplete for now
*/
[key: `$${string}`]: Partial<AxiomConfigBase> | undefined;
}
/**
* Type-safe helper for defining Axiom configuration.
*
* @param config - The configuration object
* @returns The same configuration object with type checking
*
* @example
* ```typescript
* import { defineConfig } from 'axiom/ai/config';
*
* export default defineConfig({
* eval: {
* url: process.env.AXIOM_URL,
* token: process.env.AXIOM_TOKEN,
* dataset: process.env.AXIOM_DATASET,
* include: ['**\/*.eval.{ts,js}'],
* instrumentation: ({ url, token, dataset }) => setupAppInstrumentation({ url, token, dataset }),
* },
* });
* ```
*/
declare function defineConfig(config: AxiomConfig): AxiomConfig;
export { type AxiomConfig as A, type ResolvedAxiomConfig as R, type AxiomEvalInstrumentationHook as a, defineConfig as d };