@thinkhive/sdk 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ThinkHive
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,212 @@
+# ThinkHive SDK
+
+The official JavaScript/TypeScript SDK for [ThinkHive](https://thinkhive.ai) - AI Agent Observability Platform.
+
+## Features
+
+- **Trace Analysis**: Analyze AI agent traces with detailed explainability
+- **RAG Evaluation**: 8 quality metrics for RAG systems (groundedness, faithfulness, etc.)
+- **Hallucination Detection**: 9 types of hallucination detection
+- **Business Impact**: Industry-specific ROI calculations
+- **Auto-Instrumentation**: Works with LangChain, OpenAI, Anthropic, and more
+- **OpenTelemetry**: Built on OTLP for seamless integration
+
+## Installation
+
+```bash
+npm install @thinkhive/sdk
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { ThinkHive } from '@thinkhive/sdk';
+
+// Initialize client
+const client = new ThinkHive({
+  apiKey: 'your_api_key',
+  baseUrl: 'https://api.thinkhive.ai'
+});
+
+// Send a trace
+const result = await client.trace({
+  userMessage: 'What is the weather in San Francisco?',
+  agentResponse: 'The weather in San Francisco is currently 65°F and sunny.',
+  agentId: 'weather-agent'
+});
+
+console.log(`Trace ID: ${result.traceId}`);
+if (result.analysis) {
+  console.log(`Outcome: ${result.analysis.outcome.verdict}`);
+  console.log(`Impact Score: ${result.analysis.businessImpact.impactScore}`);
+}
+```
+
+### With Business Context
+
+```typescript
+const result = await client.trace({
+  userMessage: 'I want to cancel my order #12345',
+  agentResponse: 'I understand you want to cancel order #12345...',
+  agentId: 'support-agent',
+  businessContext: {
+    customerId: 'cust_abc123',
+    transactionValue: 150.00,
+    priority: 'high',
+    industry: 'ecommerce'
+  }
+});
+
+// Access ROI metrics
+if (result.analysis?.businessImpact?.roi) {
+  const roi = result.analysis.businessImpact.roi;
+  console.log(`Estimated Revenue Loss: $${roi.estimatedRevenueLoss}`);
+  console.log(`Churn Probability: ${roi.churnProbability}%`);
+}
+```
+
+### Explainer API
+
+```typescript
+// Full trace analysis with RAG evaluation
+const analysis = await client.explainer.analyze({
+  userMessage: 'What is your return policy?',
+  agentResponse: 'Items can be returned within 30 days...',
+  retrievedContexts: ['Return Policy: 30 day returns...'],
+  outcome: 'success'
+}, {
+  tier: 'full_llm',
+  includeRagEvaluation: true,
+  includeHallucinationDetection: true
+});
+
+console.log(`Summary: ${analysis.summary}`);
+console.log(`Groundedness: ${analysis.ragEvaluation?.groundedness}`);
+
+// Batch analysis
+const batchResult = await client.explainer.analyzeBatch([
+  { userMessage: '...', agentResponse: '...' },
+  { userMessage: '...', agentResponse: '...' }
+], { tier: 'fast_llm' });
+
+// Semantic search
+const searchResults = await client.explainer.search({
+  query: 'refund complaints',
+  filters: { outcome: 'failure' },
+  limit: 10
+});
+```
+
+### Quality Metrics
+
+```typescript
+// Get RAG scores
+const ragScores = await client.quality.getRagScores('trace-123');
+console.log(`Groundedness: ${ragScores.groundedness}`);
+console.log(`Faithfulness: ${ragScores.faithfulness}`);
+
+// Get hallucination report
+const report = await client.quality.getHallucinationReport('trace-123');
+if (report.hasHallucinations) {
+  for (const detection of report.detectedTypes) {
+    console.log(`- ${detection.type}: ${detection.description}`);
+  }
+}
+
+// Evaluate RAG for custom input
+const evaluation = await client.quality.evaluateRag({
+  query: 'What is the return policy?',
+  response: 'Items can be returned within 30 days.',
+  contexts: [{ content: 'Return Policy: 30 day returns...' }]
+});
+```
+
+### ROI Analytics
+
+```typescript
+// Get ROI summary
+const summary = await client.analytics.getRoiSummary();
+console.log(`Revenue Saved: $${summary.totalRevenueSaved}`);
+
+// Get per-agent ROI
+const agentRoi = await client.analytics.getRoiByAgent('support-agent');
+console.log(`Success Rate: ${agentRoi.successRate}%`);
+
+// Get correlation analysis
+const correlations = await client.analytics.getCorrelations();
+for (const corr of correlations.correlations) {
+  console.log(`${corr.type}: ${corr.actionableInsight}`);
+}
+```
+
+### Providing Feedback
+
+```typescript
+// After receiving user feedback
+await client.feedback({
+  traceId: result.traceId,
+  rating: 5,
+  wasHelpful: true,
+  comment: 'Very accurate response!'
+});
+
+// When response was incorrect
+await client.feedback({
+  traceId: result.traceId,
+  rating: 2,
+  wasHelpful: false,
+  hadIssues: ['incorrect_info', 'too_long'],
+  correctedResponse: 'The correct answer is...'
+});
+```
+
+### Auto-Instrumentation
+
+```typescript
+import { init, autoInstrument } from '@thinkhive/sdk';
+
+// Initialize SDK
+init({
+  apiKey: 'your_api_key',
+  serviceName: 'my-ai-agent',
+  autoInstrument: true,
+  frameworks: ['langchain', 'openai']
+});
+
+// Or manually instrument
+autoInstrument(client, {
+  frameworks: ['langchain', 'openai'],
+  capturePrompts: true,
+  captureResponses: true,
+  businessContext: { industry: 'saas' }
+});
+
+// Now all LangChain and OpenAI calls are automatically traced!
+```
+
+## Analysis Tiers
+
+| Tier | Description | Latency | Cost |
+|------|-------------|---------|------|
+| `rule_based` | Pattern matching, keyword extraction | ~50ms | Free |
+| `fast_llm` | Quick LLM analysis (GPT-3.5) | ~500ms | Low |
+| `full_llm` | Complete analysis (GPT-4o) | ~3s | Standard |
+| `deep` | Multi-pass with validation | ~15s | Premium |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `THINKHIVE_API_KEY` | Your ThinkHive API key |
+| `THINKHIVE_ENDPOINT` | Custom API endpoint (optional) |
+| `THINKHIVE_SERVICE_NAME` | Service name for traces (optional) |
+
+## API Reference
+
+See [API Documentation](https://docs.thinkhive.ai/sdk/javascript/reference) for complete type definitions.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.