init()

The init() function initializes the Gentrace SDK with your API credentials and configuration options. This function must be called early in your application setup to configure the SDK globally before using any other Gentrace functionality.

Basic usage

TypeScript

typescript
import { init } from 'gentrace';
// Basic initialization with API key
init({
  apiKey: 'your-gentrace-api-key'
});
// Or using environment variable
init({
  apiKey: process.env.GENTRACE_API_KEY
});

Python

python
from gentrace import init
# Basic initialization with API key
init(api_key="your-gentrace-api-key")
# Or using environment variable
import os
from gentrace import init
init(api_key=os.environ["GENTRACE_API_KEY"])

Overview

The init() function:

1. Configures authentication with your Gentrace API key
2. Sets up global client instances for making API requests
3. Establishes connection settings like base URL, timeouts, and retry behavior
4. Enables SDK functionality by making other Gentrace functions available

Parameters

Stainless SDK Generation

The parameters and client options described in this section are automatically generated by the Stainless API SDK generation platform.

TypeScript

Function Signature

typescript
function init(options: ClientOptions = {}): void

ClientOptions

typescript
interface ClientOptions {
  apiKey?: string;
  baseURL?: string | null;
  timeout?: number;
  maxRetries?: number;
  defaultHeaders?: HeadersLike;
  defaultQuery?: Record<string, string | undefined>;
  logLevel?: LogLevel;
  logger?: Logger;
  fetchOptions?: RequestInit;
  fetch?: Fetch;
}

Parameters

• apiKey (string, optional): Your Gentrace API key. If not provided, the SDK will attempt to use the GENTRACE_API_KEY environment variable
• baseURL (string, optional): Override the default base URL for the API. Defaults to GENTRACE_BASE_URL environment variable or https://gentrace.ai/api. This is particularly useful for self-hosted Gentrace instances (e.g., http://self-hosted-gentrace.example.com/api)
• timeout (number, optional): Maximum time in milliseconds to wait for a response from the server before timing out a single request
• maxRetries (number, optional): Maximum number of times to retry a request in case of temporary failure. Default: 2
• defaultHeaders (object, optional): Default headers to include with every request to the API
• defaultQuery (object, optional): Default query parameters to include with every request to the API
• logLevel (LogLevel, optional): Set the log level. Defaults to GENTRACE_LOG environment variable or 'warn'
• logger (Logger, optional): Custom logger instance. Defaults to globalThis.console
• fetchOptions (RequestInit, optional): Additional options to be passed to fetch calls
• fetch (Fetch, optional): Custom fetch function implementation

Python

Function Signature

python
def init(
    *,
    api_key: Optional[str] = None,
    base_url: Optional[str] = None,
    **kwargs: Any
) -> None

Parameters

• api_key (str, optional): Your Gentrace API key. If not provided, the SDK will attempt to use the GENTRACE_API_KEY environment variable
• base_url (str, optional): Override the default base URL for the API. Defaults to GENTRACE_BASE_URL environment variable or https://gentrace.ai/api. This is particularly useful for self-hosted Gentrace instances (e.g., http://self-hosted-gentrace.example.com/api)
• kwargs (Any): Additional keyword arguments passed to the underlying client constructors

Additional Options (via kwargs)

• timeout (float | Timeout, optional): Maximum time to wait for a response from the server
• max_retries (int, optional): Maximum number of times to retry a request in case of temporary failure. Default: 2
• default_headers (Mapping[str, str], optional): Default headers to include with every request to the API
• default_query (Mapping[str, object], optional): Default query parameters to include with every request to the API
• http_client (httpx.Client, optional): Custom HTTP client instance for making requests

Advanced configuration

Custom base URL and timeout

TypeScript

typescript
import { init } from 'gentrace';
init({
  apiKey: process.env.GENTRACE_API_KEY,
  baseURL: 'https://your-custom-domain.com/api',
  timeout: 30000, // 30 seconds
  maxRetries: 5
});

Python

python
from gentrace import init
import os
init(
    api_key=os.environ["GENTRACE_API_KEY"],
    base_url="https://your-custom-domain.com/api",
    timeout=30.0,  # 30 seconds
    max_retries=5
)

Custom headers and logging

TypeScript

typescript
import { init } from 'gentrace';
init({
  apiKey: process.env.GENTRACE_API_KEY,
  defaultHeaders: {
    'X-Custom-Header': 'your-value',
    'User-Agent': 'MyApp/1.0.0'
  },
  logLevel: 'debug',
  logger: console // or your custom logger
});

Python

python
from gentrace import init
import os
init(
    api_key=os.environ["GENTRACE_API_KEY"],
    default_headers={
        "X-Custom-Header": "your-value",
        "User-Agent": "MyApp/1.0.0"
    }
)

Environment variables

Instead of passing configuration options directly to init(), you can use environment variables:

• GENTRACE_API_KEY: Your Gentrace API key
• GENTRACE_BASE_URL: Custom base URL for the API (useful for self-hosted instances)
• GENTRACE_LOG (TypeScript only): Log level setting

TypeScript

bash
# Set environment variables
export GENTRACE_API_KEY="your-gentrace-api-key"
export GENTRACE_BASE_URL="https://your-custom-domain.com/api"
export GENTRACE_LOG="debug"

typescript
import { init } from 'gentrace';
// Initialize without parameters - uses environment variables
init();

Python

bash
# Set environment variables
export GENTRACE_API_KEY="your-gentrace-api-key"
export GENTRACE_BASE_URL="https://your-custom-domain.com/api"

python
from gentrace import init
# Initialize without parameters - uses environment variables
init()

Error handling

The init() function will throw an error if required configuration is missing:

TypeScript

typescript
import { init } from 'gentrace';
try {
  init({
    // Missing apiKey - will throw error if GENTRACE_API_KEY env var not set
  });
} catch (error) {
  console.error('Failed to initialize Gentrace:', error.message);
}

Python

python
from gentrace import init, GentraceError
try:
    init()
    # Missing api_key - will throw error if GENTRACE_API_KEY env var not set
except GentraceError as e:
    print(f"Failed to initialize Gentrace: {e}")

Best practices

1. Initialize early

Call init() as early as possible in your application, before using any other Gentrace functionality:

TypeScript

typescript
// At the top of your main application file
import { init } from 'gentrace';
// Initialize first
init({
  apiKey: process.env.GENTRACE_API_KEY
});
// Then import and use other Gentrace functions
import { experiment, evalOnce } from 'gentrace';

Python

python
# At the top of your main application file
from gentrace import init
import os
# Initialize first
init(api_key=os.environ["GENTRACE_API_KEY"])
# Then use other Gentrace functions
from gentrace import experiment, eval

2. Use environment variables

Store sensitive configuration like API keys in environment variables rather than hardcoding them:

bash
# .env file
GENTRACE_API_KEY=your-gentrace-api-key
GENTRACE_BASE_URL=https://gentrace.ai/api

Requirements

• API Key: A valid Gentrace API key is required
• Network Access: The SDK needs to communicate with the Gentrace API
• Environment: Node.js 16+ (TypeScript) or Python 3.8+ (Python)

Related functions

• experiment() - Create testing contexts for grouping evaluations
• interaction() - Instrument AI functions for tracing
• evalDataset() / eval_dataset() - Run tests against datasets
• eval() / evalOnce() - Run individual test cases

See also

• OpenTelemetry Setup Guide
• Quickstart Guide
• Traces API Reference