Installation
Requirements
- Python 3.10+ (recommended) — also supports 3.9, 3.11, 3.12
- pip package manager
- Node.js 18+
- npm, yarn, or pnpm
Install
Configuration
Environment Variables
| Variable | Description | Required |
|---|
LUNAR_API_KEY | API key for authentication | Yes |
export LUNAR_API_KEY="your-api-key"
Client Initialization
Basic usage with environment variable:
from lunar import Lunar
client = Lunar() # Uses LUNAR_API_KEY from environment
import { Lunar } from "lunar";
const client = new Lunar(); // Uses LUNAR_API_KEY from environment
client = Lunar(api_key="your-api-key")
const client = new Lunar({ apiKey: "your-api-key" });
client = Lunar(
api_key="your-api-key",
timeout=60.0, # Request timeout in seconds
num_retries=2, # Retry attempts for failed requests
max_connections=100, # Max concurrent connections
fallbacks={ # Global fallback configuration
"gpt-4o-mini": ["claude-3-haiku", "llama-3.1-8b"],
"gpt-4": ["claude-3-opus"]
}
)
const client = new Lunar({
apiKey: "your-api-key",
timeout: 60000, // Request timeout in ms
numRetries: 2, // Retry attempts for failed requests
fallbacks: { // Global fallback configuration
"gpt-4o-mini": ["claude-3-haiku", "llama-3.1-8b"],
"gpt-4": ["claude-3-opus"],
},
});
Configuration Parameters
| Parameter | Type | Default | Description |
|---|
api_key | str | None | API key for authentication |
base_url | str | None | Custom API URL |
timeout | float | 60.0 | Request timeout in seconds |
num_retries | int | 2 | Number of retry attempts |
max_connections | int | 100 | Maximum concurrent connections |
fallbacks | dict | None | Model fallback configuration |
| Parameter | Type | Default | Description |
|---|
apiKey | string | undefined | API key for authentication |
jwt | string | undefined | JWT for authentication |
baseUrl | string | undefined | Custom API URL |
timeout | number | 60000 | Request timeout in milliseconds |
numRetries | number | 2 | Number of retry attempts |
fallbacks | Record<string, string[]> | {} | Model fallback configuration |
Using Context Manager (Python)
The Python client supports context managers for automatic resource cleanup:
Synchronous:
from lunar import Lunar
with Lunar(api_key="your-api-key") as client:
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Hello!"}]
)
# Resources automatically cleaned up
from lunar import AsyncLunar
async with AsyncLunar(api_key="your-api-key") as client:
response = await client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Hello!"}]
)
# Resources automatically cleaned up
The TypeScript SDK does not require manual resource cleanup — the underlying HTTP client is managed automatically.
Verify Installation
from lunar import Lunar
try:
client = Lunar()
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Say 'Hello from Lunar!'"}],
max_tokens=20
)
print("Success:", response.choices[0].message.content)
print(f"Cost: ${response.usage.total_cost_usd}")
except Exception as e:
print(f"Error: {e}")
import { Lunar } from "lunar";
try {
const client = new Lunar();
const response = await client.chat.completions.create({
model: "gpt-4o-mini",
messages: [{ role: "user", content: "Say 'Hello from Lunar!'" }],
max_tokens: 20,
});
console.log("Success:", response.choices[0].message.content);
console.log(`Cost: $${response.usage?.total_cost_usd}`);
} catch (e) {
console.error("Error:", e);
}
Next Steps
