@sentrial/sdk 0.1.0

package/README.md

@@ -0,0 +1,208 @@
+# @sentrial/sdk
+
+TypeScript SDK for [Sentrial](https://sentrial.com) - AI agent observability and monitoring.
+
+Track sessions, tool calls, and metrics to power:
+- **Signal detection**: Auto-detect patterns and anomalies
+- **Root cause analysis**: Understand WHY agents fail
+- **Code fixer**: AI-suggested fixes with GitHub PRs
+
+## Installation
+
+```bash
+npm install @sentrial/sdk
+# or
+pnpm add @sentrial/sdk
+# or
+yarn add @sentrial/sdk
+```
+
+## Quick Start
+
+```typescript
+import { SentrialClient } from '@sentrial/sdk';
+
+const client = new SentrialClient({
+  apiKey: process.env.SENTRIAL_API_KEY!,
+});
+
+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,
+  });
+
+  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;
+  }
+}
+```
+
+## Simple API (begin/finish pattern)
+
+```typescript
+import { sentrial } from '@sentrial/sdk';
+
+sentrial.configure({ apiKey: 'sentrial_live_xxx' });
+
+async function handleMessage(userId: string, message: string) {
+  const interaction = await sentrial.begin({
+    userId,
+    event: 'chat_message',
+    input: message,
+  });
+
+  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;
+  }
+}
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+SENTRIAL_API_URL=https://api.sentrial.com
+SENTRIAL_API_KEY=sentrial_live_xxx
+```
+
+### Explicit Configuration
+
+```typescript
+const client = new SentrialClient({
+  apiKey: 'sentrial_live_xxx',
+  apiUrl: 'https://api.sentrial.com', // Optional
+  failSilently: true, // Default: true (errors logged but don't crash)
+});
+```
+
+## Cost Calculation
+
+```typescript
+import { calculateOpenAICost, calculateAnthropicCost, calculateGoogleCost } from '@sentrial/sdk';
+
+const openaiCost = calculateOpenAICost({
+  model: 'gpt-4o',
+  inputTokens: 1000,
+  outputTokens: 500,
+});
+
+const anthropicCost = calculateAnthropicCost({
+  model: 'claude-3-5-sonnet',
+  inputTokens: 1000,
+  outputTokens: 500,
+});
+
+const googleCost = calculateGoogleCost({
+  model: 'gemini-2.0-flash',
+  inputTokens: 1000,
+  outputTokens: 500,
+});
+```
+
+## Error Handling
+
+```typescript
+import { SentrialClient, SentrialError } from '@sentrial/sdk';
+
+const client = new SentrialClient({ 
+  apiKey: '...',
+  failSilently: false, // Enable errors during development
+});
+
+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;
+}
+```
+
+## API Reference
+
+### SentrialClient
+
+```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
+
+```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;
+}
+```
+
+## License
+
+MIT