SDK Reference
Installation

Installation

Install the Grounded Intelligence SDK via npm:

npm install lumina-sdk

Note: The package is installed as lumina-sdk, but we refer to it as the Grounded Intelligence SDK throughout the documentation.

Requirements

  • Node.js 18+
  • A valid write key (gi_xxxxx) from your Grounded Intelligence dashboard

Peer Dependencies (Optional)

For provider integration, install the appropriate peer dependencies:

PostHog (UI Analytics)

npm install posthog-js

Required if using the PostHog UI provider integration.

Package Contents

The SDK includes:

Core Tracking

  • Turn events — Capture user ↔ assistant interactions
  • Session management — Sequence multiple turns under one trace

User Identity

  • Anonymous tracking — Automatic anonymous ID generation
  • Identified users — Switch to known users via identify()
  • Persistent identity — Cookies (primary) + localStorage (backup)

Data Capture

  • LLM wrapping — Auto-capture latency and errors
  • Tool recording — Track RAG, search, and API calls
  • Message transcripts — Configurable capture with PII masking
  • Annotations — Add custom metadata

Provider Integration

  • PostHog provider — UI analytics correlation (session IDs, replay URLs)

Batching & Reliability

  • Automatic batching — NDJSON event buffering
  • Configurable flush — Time and size-based triggers
  • Retry logic — Linear backoff (300ms, 600ms, 900ms), 3 attempts
  • Offline support — Queue events when offline

Developer Experience

  • TypeScript support — Full type definitions
  • Minimal bundle size — Lightweight core SDK
  • Zero required peer deps — Optional UI provider only

Verification

After installation, verify the SDK is available:

import { Lumina } from 'lumina-sdk'
 
console.log(Lumina) // Should output the Lumina object

Next Steps

QuickstartInitialization