@crevanta/stelvara-sdk 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,108 @@
+# @crevanta/stelvara-sdk
+
+TypeScript SDK for [Stelvara](https://stelvara.com) — AI Behavior Control Plane.
+
+Send traces from your Node.js or browser applications to Stelvara for observability, policy compliance, and business outcome tracking.
+
+## Installation
+
+```bash
+npm install @crevanta/stelvara-sdk
+```
+
+## Quickstart
+
+```typescript
+import { init, captureTrace, tagOutcome, shutdown } from '@crevanta/stelvara-sdk';
+
+// 1. Initialize
+init({
+  apiKey: 'stv_live_your_api_key',
+  agentId: 'your-agent-uuid',
+});
+
+// 2. Capture a trace
+const traceKey = captureTrace({
+  input: { user_message: 'What is my account balance?' },
+  model: { name: 'gpt-4', provider: 'openai' },
+  response: { text: 'Your balance is $1,234.56', tokens_used: 42 },
+  performance: { duration_ms: 320 },
+});
+
+// 3. Tag business outcomes
+if (traceKey) {
+  await tagOutcome(traceKey, {
+    customer_satisfied: true,
+    resolution_type: 'automated',
+  });
+}
+
+// 4. Shutdown (flushes pending traces)
+await shutdown();
+```
+
+## Class-Based Usage
+
+For multi-agent setups or testing, use `StelvaraClient` directly:
+
+```typescript
+import { StelvaraClient } from '@crevanta/stelvara-sdk';
+
+const client = new StelvaraClient({
+  apiKey: 'stv_live_your_api_key',
+  agentId: 'your-agent-uuid',
+});
+
+const traceKey = client.captureTrace({
+  input: { user_message: 'Hello' },
+});
+
+await client.shutdown();
+```
+
+## Session Tracking & Trace Hierarchy
+
+Track multi-turn conversations and parent/child trace relationships:
+
+```typescript
+const traceKey = captureTrace(
+  { input: { user_message: 'Follow-up question' } },
+  {
+    sessionId: 'conversation-abc-123',
+    parentTraceId: 'parent-trace-uuid',
+    traceType: 'chat',
+  }
+);
+```
+
+### Trace Types
+
+- `completion` — Single LLM completion
+- `chat` — Multi-turn chat interaction
+- `agent_step` — One step in an agent workflow
+- `tool_use` — Tool/function call
+- `custom` — Custom trace type
+
+## Configuration
+
+```typescript
+init({
+  apiKey: 'stv_live_...', // Required. API key (stv_ prefix).
+  agentId: 'uuid', // Required. Agent UUID.
+  endpoint: 'https://...', // Optional. Supabase Edge Functions URL.
+  bufferSize: 100, // Optional. Max buffered traces (default: 100).
+  batchSize: 50, // Optional. Traces per API batch (default: 50).
+  flushIntervalMs: 5000, // Optional. Flush interval in ms (default: 5000).
+  maxRetries: 3, // Optional. Retry attempts (default: 3).
+  enabled: true, // Optional. Kill switch (default: true).
+});
+```
+
+## Requirements
+
+- Node.js >= 18 (uses global `fetch`)
+- Modern browsers with `fetch` support
+
+## License
+
+MIT