Introduction

Grounded Intelligence SDK

Connect your AI workflows to every surrounding data stream — session replays, user feedback, observability traces, and more.

npm version (opens in a new tab) License: MIT TypeScript (opens in a new tab)

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

What This SDK Enables

  • Capture AI Conversations: Track every user ↔ assistant interaction with automatic latency, error capture, and context
  • Connect to Session Replays: Correlate AI conversations with session replays from PostHog, Amplitude, or any analytics provider
  • Track Tool & API Calls: Monitor external API calls, database queries, and function executions made by your AI
  • Unified User Identity: Seamlessly transition from anonymous to identified users across all data streams
  • Privacy-First: Built-in transcript masking and PII filtering

Key Features

  • Minimal Overhead: Buffered NDJSON transport with automatic batching
  • Session Management: W3C Trace Context standard for distributed tracing
  • Persistent Identity: Cookie + localStorage for identity across sessions and tabs
  • Provider Integrations: Works with any analytics provider (PostHog, Amplitude, Datadog, etc.) — built-in PostHog helper included
  • Type Safe: Full TypeScript support with exported types

Quick Start

npm install lumina-sdk
import { Lumina, CaptureTranscript } from 'lumina-sdk'
 
// Initialize once at app startup
Lumina.init({
  endpoint: 'https://your-ingest-server.com',
  writeKey: 'gi_xxxxx',
  captureTranscript: CaptureTranscript.Full,
  enableToolWrapping: true,
  uiAnalytics: createDummyProvider(),
})
 
// Start a session and capture a turn
const session = await Lumina.session.start()
const turn = session.turn()
 
const response = await turn.wrapLLM(
  async () => await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: 'Hello!' }],
  }),
  { model: 'gpt-4o', prompt_id: 'greeting_v1' }
)
 
turn.setMessages([
  { role: 'user', content: 'Hello!' },
  { role: 'assistant', content: response.choices[0].message.content || '' },
])
 
await turn.finish()

Get Started →

Core Concepts

Turn Event

A turn represents a single user ↔ assistant interaction, capturing latency, model info, transcript, tool calls, retrieval data, and custom annotations.

Session

A session is a sequence of turns under a single trace ID, using W3C Trace Context standard and persisting across page reloads.

Identity

Users can be anonymous (anon_<uuid>) or identified via Lumina.identify(). Identity persists in cookies and localStorage.

Documentation

Getting Started

SDK Reference

What's Coming

Grounded Intelligence is actively building integrations for:

  • Customer support platforms (Intercom, Zendesk)
  • Observability providers (DataDog, Sentry, OpenTelemetry)
  • Payment & business events (Stripe, custom webhooks)
  • User feedback systems (in-app surveys, feature requests)

Support

For issues, questions, or feature requests:

License

MIT

Quickstart