> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselumina.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete API reference for Lumina TypeScript/JavaScript SDK

Complete reference for `@uselumina/sdk`.

***

## initLumina(config)

Initialize the Lumina client.

**Parameters:**

| Parameter             | Type    | Required | Description                    |
| --------------------- | ------- | -------- | ------------------------------ |
| `config.endpoint`     | string  | Yes      | OTLP endpoint URL              |
| `config.service_name` | string  | Yes      | Service identifier             |
| `config.enabled`      | boolean | No       | Enable tracing (default: true) |
| `config.resource`     | object  | No       | Resource attributes            |

**Returns:** `Lumina` instance

**Example:**

```typescript theme={null}
const lumina = initLumina({
  endpoint: 'http://localhost:9411/v1/traces',
  service_name: 'my-service',
});
```

***

## lumina.traceLLM(fn, options)

Trace an LLM call with automatic attribute extraction.

**Parameters:**

| Parameter          | Type               | Required | Description                           |
| ------------------ | ------------------ | -------- | ------------------------------------- |
| `fn`               | `() => Promise<T>` | Yes      | Async function returning LLM response |
| `options.name`     | string             | No       | Span name                             |
| `options.system`   | string             | No       | Provider (openai, anthropic)          |
| `options.prompt`   | string             | No       | Input prompt                          |
| `options.metadata` | object             | No       | Custom attributes                     |

**Returns:** `Promise<T>`

**Example:**

```typescript theme={null}
await lumina.traceLLM(
  () => openai.chat.completions.create({ model: 'gpt-4', messages }),
  { name: 'chat', system: 'openai', prompt: userMessage }
);
```

***

## lumina.trace(name, fn)

Create a parent span for hierarchical tracing.

**Parameters:**

| Parameter | Type                         | Required | Description             |
| --------- | ---------------------------- | -------- | ----------------------- |
| `name`    | string                       | Yes      | Span name               |
| `fn`      | `(span: Span) => Promise<T>` | Yes      | Async function to trace |

**Returns:** `Promise<T>`

**Example:**

```typescript theme={null}
await lumina.trace('rag_pipeline', async (span) => {
  span.setAttribute('query', query);
  // Your code here
});
```

***

## lumina.flush()

Flush all buffered spans immediately.

**Returns:** `Promise<void>`

***

## lumina.shutdown()

Flush and shut down the SDK.

**Returns:** `Promise<void>`

***

## Span API

**span.setAttribute(key, value)**

Add attribute to span.

```typescript theme={null}
span.setAttribute('userId', 'user-123');
span.setAttribute('cost', 0.003);
```

**span.addEvent(name, attributes?)**

Add event to span.

```typescript theme={null}
span.addEvent('processing_started');
span.addEvent('checkpoint', { progress: 50 });
```

**span.setStatus(status)**

Set span status.

```typescript theme={null}
span.setStatus({ code: 'OK' });
span.setStatus({ code: 'ERROR', message: 'Failed to process' });
```