@sentrial/sdk 0.1.0 → 0.3.0

package/README.md

@@ -5,6 +5,7 @@ TypeScript SDK for [Sentrial](https://sentrial.com) - AI agent observability and
 Track sessions, tool calls, and metrics to power:
 - **Signal detection**: Auto-detect patterns and anomalies
 - **Root cause analysis**: Understand WHY agents fail
+- **Experiments**: A/B test different system prompts
 - **Code fixer**: AI-suggested fixes with GitHub PRs
 
 ## Installation
@@ -17,89 +18,151 @@ pnpm add @sentrial/sdk
 yarn add @sentrial/sdk
 ```
 
-## Quick Start
+## Quick Start (30 seconds)
+
+### Option 1: Auto-Wrap LLM Clients (Recommended)
 
 ```typescript
-import { SentrialClient } from '@sentrial/sdk';
+import OpenAI from 'openai';
+import { wrapOpenAI, withSession, configure } from '@sentrial/sdk';
 
-const client = new SentrialClient({
-  apiKey: process.env.SENTRIAL_API_KEY!,
-});
+configure({ apiKey: 'sentrial_live_xxx' });
 
-async function runAgent(userId: string, input: string) {
-  // 1. Create session
-  const sessionId = await client.createSession({
-    name: `Support: ${input.slice(0, 50)}`,
-    agentName: 'support-agent',
-    userId,
+// Wrap once - all calls auto-tracked!
+const openai = wrapOpenAI(new OpenAI());
+
+const myAgent = withSession('support-agent', async (userId: string, message: string) => {
+  // LLM calls automatically tracked with tokens, cost, latency
+  const response = await openai.chat.completions.create({
+    model: 'gpt-4o',
+    messages: [{ role: 'user', content: message }],
   });
+  return response.choices[0].message.content;
+});
 
-  try {
-    // 2. Track tool calls
-    await client.trackToolCall({
-      sessionId,
-      toolName: 'search_kb',
-      toolInput: { query: input },
-      toolOutput: { articles: ['KB-001'] },
-      reasoning: 'Searching knowledge base',
-    });
-
-    // 3. Process and respond
-    const response = await processInput(input);
-
-    // 4. Complete session
-    await client.completeSession({
-      sessionId,
-      success: true,
-      customMetrics: { satisfaction: 4.5 },
-    });
-
-    return response;
-  } catch (error) {
-    await client.completeSession({
-      sessionId,
-      success: false,
-      failureReason: error instanceof Error ? error.message : 'Unknown error',
-    });
-    throw error;
-  }
-}
+await myAgent('user_123', 'How do I reset my password?');
 ```
 
-## Simple API (begin/finish pattern)
+### Option 2: Decorators / Higher-Order Functions
 
 ```typescript
-import { sentrial } from '@sentrial/sdk';
+import { withTool, withSession, configure } from '@sentrial/sdk';
 
-sentrial.configure({ apiKey: 'sentrial_live_xxx' });
+configure({ apiKey: 'sentrial_live_xxx' });
 
-async function handleMessage(userId: string, message: string) {
-  const interaction = await sentrial.begin({
-    userId,
-    event: 'chat_message',
-    input: message,
-  });
+// Track tools
+const searchKB = withTool('search_kb', async (query: string) => {
+  return { articles: ['KB-001', 'KB-002'] };
+});
+
+// Track sessions
+const supportAgent = withSession('support-agent', async (userId: string, message: string) => {
+  const results = await searchKB(message); // Auto-tracked!
+  return `Found ${results.articles.length} articles`;
+});
+```
+
+### Option 3: Vercel AI SDK
+
+```typescript
+import { configure, wrapAISDK } from '@sentrial/sdk';
+import * as ai from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+configure({ apiKey: process.env.SENTRIAL_API_KEY, defaultAgent: 'my-agent' });
+
+const { generateText, streamText } = wrapAISDK(ai);
+
+// All calls automatically traced!
+const { text } = await generateText({
+  model: openai('gpt-4'),
+  prompt: 'What is the capital of France?',
+});
+```
+
+## Features
 
-  try {
-    const response = await agent.process(message);
-
-    await interaction.finish({
-      output: response,
-      success: true,
-      customMetrics: { satisfaction: 4.5 },
-    });
-
-    return response;
-  } catch (error) {
-    await interaction.finish({
-      success: false,
-      failureReason: error.message,
-    });
-    throw error;
-  }
+### LLM Auto-Wrappers
+
+Wrap once, track everything automatically:
+
+```typescript
+import { wrapOpenAI, wrapAnthropic, wrapGoogle, wrapLLM } from '@sentrial/sdk';
+
+// OpenAI
+const openai = wrapOpenAI(new OpenAI());
+
+// Anthropic
+const anthropic = wrapAnthropic(new Anthropic());
+
+// Google Gemini
+const model = wrapGoogle(genAI.getGenerativeModel({ model: 'gemini-2.0-flash' }));
+
+// Auto-detect
+const client = wrapLLM(new OpenAI()); // Detects OpenAI, Anthropic, or Google
+```
+
+### Decorators
+
+```typescript
+import { withTool, withSession, Tool, TrackSession } from '@sentrial/sdk';
+
+// Higher-order functions
+const searchWeb = withTool('web_search', async (query: string) => {...});
+const myAgent = withSession('my-agent', async (userId, message) => {...});
+
+// Class decorators (with experimentalDecorators)
+class MyAgent {
+  @Tool('search')
+  async searchWeb(query: string) {...}
+
+  @TrackSession('my-agent')
+  async handleRequest(userId: string, message: string) {...}
 }
 ```
 
+### Experiments
+
+A/B test different system prompts:
+
+```typescript
+import { Experiment, getSystemPrompt, isExperimentMode } from '@sentrial/sdk';
+
+const experiment = new Experiment('exp_abc123');
+await experiment.load();
+
+await experiment.run(async (testCase, variant, tracker) => {
+  const systemPrompt = getSystemPrompt('Default prompt');
+  const response = await runAgent(testCase.userInput, systemPrompt);
+  tracker.setResultSessionId(sessionId);
+});
+```
+
+### Vercel AI SDK Integration
+
+Full support for Vercel AI SDK v3-v6:
+
+```typescript
+import { wrapAISDK } from '@sentrial/sdk';
+import * as ai from 'ai';
+import { z } from 'zod';
+
+const { generateText, streamText, generateObject, streamObject } = wrapAISDK(ai);
+
+// With tools
+const { text } = await generateText({
+  model: openai('gpt-4'),
+  prompt: "What's the weather?",
+  tools: {
+    getWeather: {
+      description: 'Get weather',
+      parameters: z.object({ location: z.string() }),
+      execute: async ({ location }) => ({ temp: 72 }), // Auto-tracked!
+    },
+  },
+});
+```
+
 ## Configuration
 
 ### Environment Variables
@@ -109,100 +172,110 @@ SENTRIAL_API_URL=https://api.sentrial.com
 SENTRIAL_API_KEY=sentrial_live_xxx
 ```
 
-### Explicit Configuration
+### Programmatic
 
 ```typescript
-const client = new SentrialClient({
+import { configure } from '@sentrial/sdk';
+
+configure({
   apiKey: 'sentrial_live_xxx',
   apiUrl: 'https://api.sentrial.com', // Optional
-  failSilently: true, // Default: true (errors logged but don't crash)
 });
 ```
 
-## Cost Calculation
+## Full API
+
+For maximum control:
 
 ```typescript
-import { calculateOpenAICost, calculateAnthropicCost, calculateGoogleCost } from '@sentrial/sdk';
+import { SentrialClient } from '@sentrial/sdk';
 
-const openaiCost = calculateOpenAICost({
-  model: 'gpt-4o',
-  inputTokens: 1000,
-  outputTokens: 500,
-});
+const client = new SentrialClient({ apiKey: '...' });
 
-const anthropicCost = calculateAnthropicCost({
-  model: 'claude-3-5-sonnet',
-  inputTokens: 1000,
-  outputTokens: 500,
+// Create session
+const sessionId = await client.createSession({
+  name: 'Support Request',
+  agentName: 'support-agent',
+  userId: 'user_123',
 });
 
-const googleCost = calculateGoogleCost({
-  model: 'gemini-2.0-flash',
-  inputTokens: 1000,
-  outputTokens: 500,
+// Track tool calls
+await client.trackToolCall({
+  sessionId,
+  toolName: 'search_kb',
+  toolInput: { query: 'password reset' },
+  toolOutput: { articles: ['KB-001'] },
+  reasoning: 'User asked about password reset',
 });
-```
-
-## Error Handling
-
-```typescript
-import { SentrialClient, SentrialError } from '@sentrial/sdk';
 
-const client = new SentrialClient({ 
-  apiKey: '...',
-  failSilently: false, // Enable errors during development
+// Track decisions
+await client.trackDecision({
+  sessionId,
+  reasoning: 'Found relevant article, sharing with user',
+  alternatives: ['Escalate', 'Ask clarifying question'],
+  confidence: 0.9,
 });
 
-try {
-  await client.createSession({...});
-} catch (error) {
-  if (error instanceof SentrialError) {
-    if (error.isAuthError()) {
-      console.error('Invalid API key');
-    } else if (error.isRateLimitError()) {
-      console.error('Rate limited');
-    }
-  }
-  throw error;
-}
+// Complete session
+await client.completeSession({
+  sessionId,
+  success: true,
+  customMetrics: { satisfaction: 4.5 },
+  promptTokens: 1500,
+  completionTokens: 500,
+});
 ```
 
-## API Reference
-
-### SentrialClient
+## Cost Calculation
 
 ```typescript
-class SentrialClient {
-  constructor(config?: SentrialClientConfig);
-  
-  createSession(params: CreateSessionParams): Promise<string | null>;
-  trackToolCall(params: TrackToolCallParams): Promise<Event | null>;
-  trackDecision(params: TrackDecisionParams): Promise<Event | null>;
-  trackError(params: TrackErrorParams): Promise<Event | null>;
-  completeSession(params: CompleteSessionParams): Promise<Session | null>;
-  begin(params: BeginParams): Promise<Interaction>;
-  
-  // Static cost calculators
-  static calculateOpenAICost(params: CostParams): number;
-  static calculateAnthropicCost(params: CostParams): number;
-  static calculateGoogleCost(params: CostParams): number;
-}
-```
-
-### Interaction
+import { calculateOpenAICost, calculateAnthropicCost, calculateGoogleCost } from '@sentrial/sdk';
 
-```typescript
-class Interaction {
-  setOutput(output: string): void;
-  finish(params?: FinishParams): Promise<Session | null>;
-  trackToolCall(params: Omit<TrackToolCallParams, 'sessionId'>): Promise<Event | null>;
-  trackDecision(params: Omit<TrackDecisionParams, 'sessionId'>): Promise<Event | null>;
-  trackError(params: Omit<TrackErrorParams, 'sessionId'>): Promise<Event | null>;
-  getSessionId(): string | null;
-  isDegraded(): boolean;
-}
+const cost = calculateOpenAICost({
+  model: 'gpt-4o',
+  inputTokens: 1000,
+  outputTokens: 500,
+});
+// Returns: 0.0075
 ```
 
+## What Gets Tracked
+
+| Data | Auto-tracked | Manual |
+|------|-------------|--------|
+| LLM calls | ✔️ via wrappers | `trackToolCall()` |
+| Token usage | ✔️ via wrappers | `promptTokens` param |
+| Cost (USD) | ✔️ calculated | `estimatedCost` param |
+| Latency | ✔️ always | - |
+| Tool calls | ✔️ via `withTool` | `trackToolCall()` |
+| Errors | ✔️ always | `trackError()` |
+| User ID | ✔️ via session | `userId` param |
+| Custom metrics | - | `customMetrics` param |
+
+## Framework Compatibility
+
+| Framework | Integration | Status |
+|-----------|-------------|--------|
+| **Direct OpenAI** | `wrapOpenAI()` | ✔️ |
+| **Direct Anthropic** | `wrapAnthropic()` | ✔️ |
+| **Direct Gemini** | `wrapGoogle()` | ✔️ |
+| **Vercel AI SDK** | `wrapAISDK()` | ✔️ |
+| **Express/Fastify** | Decorators | ✔️ |
+| **Next.js** | Decorators | ✔️ |
+| **Custom agents** | Full API | ✔️ |
+
+## Documentation
+
+See the `docs/` folder in the repository:
+- `docs/sdks/typescript-sdk.md` - Full SDK reference
+- `docs/integrations/vercel-ai-sdk.md` - Vercel AI SDK integration
+- `docs/features/experiments.md` - Experiments guide
+
+## Support
+- 💬 [Discord](https://discord.gg/9bMmJCXt)
+- 📧 [Email](mailto:neel@sentrial.com)
+- 🐛 [GitHub Issues](https://github.com/neelshar/Sentrial/issues)
+
 ## License
 
 MIT