Lunary Python SDK

1.4.41 verified Fri May 01 auth: no python

Python SDK for Lunary, an open-source platform for managing, monitoring, and improving LLM chatbots. Current version 1.4.41, actively maintained with frequent releases.

pip install lunary

Common errors

error ImportError: cannot import name 'LunaryCallbackHandler' from 'langchain.callbacks' ↓

cause Trying to use an old import path from langchain integration that is no longer supported.

fix

Use 'from lunary import LunaryHandler' instead.

error lunary.exceptions.AuthenticationError: Invalid API key ↓

cause Environment variable LUNARY_PUBLIC_KEY is not set or contains an invalid key.

fix

Ensure LUNARY_PUBLIC_KEY is set correctly. Check your Lunary dashboard for the correct public key.

error AttributeError: module 'lunary' has no attribute 'track_event' ↓

cause Using an outdated method name; the function might have been renamed or moved.

fix

Use 'from lunary import log_event' and call log_event() instead.

Warnings

gotcha Do NOT use the deprecated langchain callback import path. The correct import is from lunary import LunaryHandler. ↓

fix Use 'from lunary import LunaryHandler' instead of 'from langchain.callbacks import LunaryCallbackHandler'.

gotcha The environment variable for API key is LUNARY_PUBLIC_KEY (not LUNARY_API_KEY). Some older docs may mention the wrong name. ↓

fix Set os.environ['LUNARY_PUBLIC_KEY'] = 'your-key'.

deprecated The 'track_event' method is part of the v1 API and may be deprecated in future versions. Use 'log_event' or the callback decorator instead. ↓

fix Switch to from lunary import log_event or use the @callback decorator.

Imports

LunaryHandler
wrong
```
from langchain.callbacks import LunaryCallbackHandler
```
correct
```
from lunary import LunaryHandler
```
Old import path from langchain integration, not the standalone SDK.
callback
```
from lunary import callback
```
log_event
```
from lunary import log_event
```

Quickstart

Initialize LunaryHandler with your API key and track an event.

import os
from lunary import LunaryHandler

# Set your Lunary API key
os.environ['LUNARY_PUBLIC_KEY'] = 'your-public-key'

handler = LunaryHandler(
    public_key=os.environ.get('LUNARY_PUBLIC_KEY', ''),
    # Optional: specify a different endpoint
    # endpoint="https://api.lunary.ai"
)

# Usage example: track a chat completion
handler.track_event("chat", {
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "Hello"}],
    "output": "Hi there!"
})