@thinkhive/sdk 4.2.0 → 4.2.1

package/README.md

@@ -1,4 +1,4 @@
-# ThinkHive SDK v4.1.0
+# ThinkHive SDK v4.2.0
 
 The official JavaScript/TypeScript SDK for [ThinkHive](https://thinkhive.ai) - AI Agent Observability Platform.
 
@@ -73,6 +73,19 @@ await shutdown();
 | `conversationEval` | Multi-turn conversation grading |
 | `transcriptPatterns` | Pattern detection in transcripts |
 
+### Operations & Monitoring APIs
+
+| API | Description |
+|-----|-------------|
+| `evalRuns` | Create, manage, and query evaluation runs |
+| `signals` | Behavioral signal configuration, stats, and trends |
+| `notifications` | Alert rules and notification management |
+| `documents` | Agent RAG document upload and management |
+| `shadowTests` | Shadow test creation and execution |
+| `sessions` | Trace session grouping and querying |
+| `drift` | Model/behavior drift detection |
+| `llmCosts` | LLM usage cost tracking and optimization |
+
 ### Legacy APIs (V2)
 
 | API | Description |
@@ -520,7 +533,153 @@ import { customerContext, captureCustomerContext } from '@thinkhive/sdk/integrat
 | `THINKHIVE_SERVICE_NAME` | Service name for traces (optional) |
 | `THINKHIVE_AGENT_ID` | Default agent ID (optional) |
 
-## Upgrading from v4.0
+## Eval Runs
+
+```typescript
+import { evalRuns } from '@thinkhive/sdk';
+
+// Create an evaluation run
+const run = await evalRuns.create('agent-123', { confidenceLevel: 'medium' });
+
+// Get results
+const results = await evalRuns.getResults(run.id, { limit: 50 });
+
+// Estimate cost before running
+const cost = await evalRuns.estimateCost('agent-123', { confidenceLevel: 'high' });
+
+// List recent runs
+const runs = await evalRuns.list({ agentId: 'agent-123', limit: 10 });
+```
+
+## Signals
+
+```typescript
+import { signals } from '@thinkhive/sdk';
+
+// List all signals
+const allSignals = await signals.list();
+
+// Create a custom behavioral signal
+await signals.create('Escalation Request', 'negative', {
+  type: 'keywords',
+  keywords: ['speak to manager', 'escalate'],
+});
+
+// Get signal stats and trends
+const stats = await signals.getStats({ agentId: 'agent-123' });
+const trends = await signals.getTrends({ granularity: 'daily' });
+```
+
+## Notifications
+
+```typescript
+import { notifications } from '@thinkhive/sdk';
+
+// Create an alert rule
+await notifications.createRule({
+  agentId: 'agent-123',
+  name: 'High failure rate alert',
+  eventType: 'failure_spike',
+  condition: { threshold: 0.3 },
+  channel: 'email',
+  target: 'team@company.com',
+});
+
+// List notifications
+const alerts = await notifications.listNotifications('agent-123', true);
+```
+
+## Documents (RAG)
+
+```typescript
+import { documents } from '@thinkhive/sdk';
+
+// Upload a document
+await documents.upload('agent-123', 'faq.txt', 'text/plain', 1024);
+
+// List agent documents
+const docs = await documents.list('agent-123');
+
+// Delete a document
+await documents.remove('agent-123', 'doc-456');
+```
+
+## Shadow Tests
+
+```typescript
+import { shadowTests } from '@thinkhive/sdk';
+
+// Create a shadow test
+await shadowTests.create({
+  fixId: 'fix-456',
+  agentId: 'agent-123',
+  testName: 'Refund policy test',
+  inputData: { message: 'How do I get a refund?' },
+  expectedOutput: 'You can request a refund within 30 days.',
+});
+
+// List tests for an agent
+const tests = await shadowTests.list('agent-123');
+```
+
+## Sessions
+
+```typescript
+import { sessions } from '@thinkhive/sdk';
+
+// List conversation sessions
+const allSessions = await sessions.list('agent-123', { limit: 20 });
+
+// Get all traces in a session
+const traces = await sessions.getTraces('session-789', 'agent-123');
+```
+
+## Drift Detection
+
+```typescript
+import { drift, hasDrift, getDriftSeverity } from '@thinkhive/sdk';
+
+// Detect drift for an agent
+const report = await drift.detect('agent-123');
+if (hasDrift(report)) {
+  console.log(`Drift severity: ${getDriftSeverity(report)}`);
+}
+
+// Detect drift across all agents
+const allDrift = await drift.detectAll();
+```
+
+## LLM Costs
+
+```typescript
+import { llmCosts, formatCost } from '@thinkhive/sdk';
+
+// Get cost summary
+const summary = await llmCosts.getSummary({ period: '30d' });
+console.log(`Total cost: ${formatCost(summary.totalCost)}`);
+
+// Get per-agent breakdown
+const breakdown = await llmCosts.getBreakdown('agent-123');
+
+// Get optimization savings
+const savings = await llmCosts.getSavings();
+```
+
+## Upgrading
+
+### v4.1.0 → v4.2.0
+
+New in v4.2.0:
+- **`evalRuns`** — create, list, and manage evaluation runs programmatically
+- **`signals`** — behavioral signal CRUD with stats and trends
+- **`notifications`** — alert rule configuration and notification management
+- **`documents`** — agent RAG document upload/list/delete
+- **`shadowTests`** — shadow test creation and management
+- **`sessions`** — trace session grouping and querying
+- **`drift`** — model/behavior drift detection with helpers
+- **`llmCosts`** — LLM usage cost tracking and optimization savings
+
+### v4.0 → v4.1.0
 
 - `roiAnalytics` now includes V3 methods: `getConfig()`, `createConfig()`, `updateConfig()`, `configVersions()`, `calculateV3()`, `trendV3()`
 - `linking` now includes: `autoLink()`, `stats()`, `generateMarker()`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkhive/sdk",
-  "version": "4.2.0",
+  "version": "4.2.1",
   "description": "ThinkHive SDK v4.0 - AI agent observability with business metrics, ROI analytics, and 25+ trace format support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",