moda-ai 0.1.1

package/README.md

@@ -0,0 +1,272 @@
+# moda-ai
+
+Official TypeScript/Node.js SDK for Moda LLM observability with automatic conversation threading.
+
+## Features
+
+- **Automatic Instrumentation**: Zero-config tracing for OpenAI and Anthropic clients
+- **Conversation Threading**: Groups multi-turn conversations together
+- **Streaming Support**: Full support for streaming responses
+- **User Tracking**: Associate LLM calls with specific users
+- **OpenTelemetry Native**: Built on OpenTelemetry for standard-compliant telemetry
+
+## Installation
+
+```bash
+npm install moda-ai
+```
+
+## Quick Start
+
+```typescript
+import { Moda } from 'moda-ai';
+import OpenAI from 'openai';
+
+// Initialize once at application startup
+Moda.init('moda_your_api_key');
+
+// Set conversation ID for your session (recommended)
+Moda.conversationId = 'session_' + sessionId;
+
+// All OpenAI calls are now automatically tracked
+const openai = new OpenAI();
+
+const response = await openai.chat.completions.create({
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'Hello!' }],
+});
+
+// Flush before exit
+await Moda.flush();
+```
+
+## Conversation Tracking
+
+### Setting Conversation ID (Recommended)
+
+For production use, explicitly set a conversation ID to group related LLM calls:
+
+```typescript
+// Property-style API (recommended)
+Moda.conversationId = 'support_ticket_123';
+await openai.chat.completions.create({ ... });
+await openai.chat.completions.create({ ... });
+// Both calls share the same conversation_id
+Moda.conversationId = null;  // clear when done
+
+// Method-style API (also supported)
+Moda.setConversationId('support_ticket_123');
+await openai.chat.completions.create({ ... });
+Moda.clearConversationId();
+```
+
+### Setting User ID
+
+Associate LLM calls with specific users:
+
+```typescript
+Moda.userId = 'user_12345';
+await openai.chat.completions.create({ ... });
+Moda.userId = null;  // clear when done
+
+// Or use method-style
+Moda.setUserId('user_12345');
+await openai.chat.completions.create({ ... });
+Moda.clearUserId();
+```
+
+### Scoped Context
+
+For callback-based scoping (useful in async contexts):
+
+```typescript
+import { withConversationId, withUserId, withContext } from 'moda-ai';
+
+// Scoped conversation ID
+await withConversationId('my_session_123', async () => {
+  await openai.chat.completions.create({ ... });
+  await openai.chat.completions.create({ ... });
+  // Both calls use 'my_session_123'
+});
+
+// Scoped user ID
+await withUserId('user_456', async () => {
+  await openai.chat.completions.create({ ... });
+});
+
+// Both at once
+await withContext('conv_123', 'user_456', async () => {
+  // ...
+});
+```
+
+## Automatic Fallback
+
+If you don't set a conversation ID, the SDK automatically computes one from the first user message and system prompt. This works well for simple use cases but explicit IDs are recommended for production:
+
+```typescript
+// Turn 1
+let messages = [{ role: 'user', content: 'Hi, help with TypeScript' }];
+const r1 = await openai.chat.completions.create({ model: 'gpt-4', messages });
+
+// Turn 2 - automatically linked to Turn 1
+messages.push({ role: 'assistant', content: r1.choices[0].message.content });
+messages.push({ role: 'user', content: 'How do I read a file?' });
+const r2 = await openai.chat.completions.create({ model: 'gpt-4', messages });
+
+// Both turns have the SAME conversation_id in your Moda dashboard
+```
+
+## Anthropic Support
+
+Works the same way with Anthropic's Claude:
+
+```typescript
+import Anthropic from '@anthropic-ai/sdk';
+
+const anthropic = new Anthropic();
+
+Moda.conversationId = 'claude_session_123';
+
+const response = await anthropic.messages.create({
+  model: 'claude-3-haiku-20240307',
+  max_tokens: 1024,
+  system: 'You are a helpful assistant.',
+  messages: [{ role: 'user', content: 'Hello!' }],
+});
+```
+
+## Streaming Support
+
+The SDK fully supports streaming responses:
+
+```typescript
+const stream = await openai.chat.completions.create({
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'Count to 5' }],
+  stream: true,
+});
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta?.content || '');
+}
+// Streaming responses are automatically tracked
+```
+
+## Configuration Options
+
+```typescript
+Moda.init('moda_api_key', {
+  // Base URL for telemetry ingestion
+  baseUrl: 'https://ingest.moda.so/v1/traces',
+
+  // Environment name (shown in dashboard)
+  environment: 'production',
+
+  // Enable/disable the SDK
+  enabled: true,
+
+  // Enable debug logging
+  debug: false,
+
+  // Batch size for telemetry export
+  batchSize: 100,
+
+  // Flush interval in milliseconds
+  flushInterval: 5000,
+});
+```
+
+## API Reference
+
+### Moda Object
+
+```typescript
+// Initialize the SDK
+Moda.init(apiKey: string, options?: ModaInitOptions): void
+
+// Force flush pending telemetry
+Moda.flush(): Promise<void>
+
+// Shutdown and release resources
+Moda.shutdown(): Promise<void>
+
+// Check initialization status
+Moda.isInitialized(): boolean
+
+// Property-style context (recommended)
+Moda.conversationId: string | null  // get/set
+Moda.userId: string | null          // get/set
+
+// Method-style context (also supported)
+Moda.setConversationId(id: string): void
+Moda.clearConversationId(): void
+Moda.setUserId(id: string): void
+Moda.clearUserId(): void
+```
+
+### Context Functions
+
+```typescript
+import { withConversationId, withUserId, withContext } from 'moda-ai';
+
+// Scoped conversation ID
+await withConversationId('conv_123', async () => {
+  // All LLM calls here use 'conv_123'
+});
+
+// Scoped user ID
+await withUserId('user_456', async () => {
+  // All LLM calls here are associated with 'user_456'
+});
+
+// Both at once
+await withContext('conv_123', 'user_456', async () => {
+  // ...
+});
+```
+
+### Utility Functions
+
+```typescript
+import { computeConversationId, generateRandomConversationId } from 'moda-ai';
+
+// Compute conversation ID from messages (same algorithm SDK uses)
+const id = computeConversationId(messages, systemPrompt);
+
+// Generate a random conversation ID
+const randomId = generateRandomConversationId();
+```
+
+## Graceful Shutdown
+
+Always flush before your application exits:
+
+```typescript
+process.on('SIGTERM', async () => {
+  await Moda.flush();
+  await Moda.shutdown();
+  process.exit(0);
+});
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+- TypeScript >= 5.0 (for type definitions)
+
+## Peer Dependencies
+
+Install the LLM clients you want to use:
+
+```bash
+# For OpenAI
+npm install openai
+
+# For Anthropic
+npm install @anthropic-ai/sdk
+```
+
+## License
+
+MIT