aigie-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Kyte AI
+
+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,501 @@
+# @kyte/sdk - TypeScript/JavaScript SDK
+
+Official TypeScript/JavaScript SDK for **Kyte** - AI Agent Monitoring and Autonomous Remediation.
+
+[![npm version](https://badge.fury.io/js/@kyte%2Fsdk.svg)](https://www.npmjs.com/package/@kyte/sdk)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## ✨ Features
+
+- 🎯 **Automatic Tracing** - Zero-config tracing with `@traceable` decorator
+- 🔄 **Framework Wrappers** - Auto-trace OpenAI, Anthropic, and more
+- 📊 **Full Observability** - Traces, spans, metrics, and scores
+- 🤖 **Autonomous Remediation** - Automatic error fixing in production
+- 🛡️ **Proactive Prevention** - Prevent errors before they happen
+- 📈 **Context Tracking** - AsyncLocalStorage for automatic parent-child relationships
+- 💪 **Full Type Safety** - Complete TypeScript definitions
+- 📦 **Dual Package** - ESM and CommonJS support
+- 🚀 **Production Ready** - Batching, error handling, zero dependencies
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @kyte/sdk
+# or
+yarn add @kyte/sdk
+# or
+pnpm add @kyte/sdk
+```
+
+### Optional Peer Dependencies
+
+```bash
+# For OpenAI integration
+npm install openai
+
+# For Anthropic integration
+npm install @anthropic-ai/sdk
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Initialize Kyte
+
+```typescript
+import { initKyte } from '@kyte/sdk';
+
+initKyte({
+  apiUrl: 'https://your-kyte-instance.com/api',
+  apiKey: process.env.KYTE_API_KEY!,
+  projectName: 'my-project',
+});
+```
+
+### 2. Auto-Trace OpenAI Calls
+
+```typescript
+import OpenAI from 'openai';
+import { wrapOpenAI } from '@kyte/sdk';
+
+const openai = wrapOpenAI(new OpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+}));
+
+// All calls are automatically traced!
+const completion = await openai.chat.completions.create({
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'Hello!' }],
+});
+```
+
+### 3. Use the `@traceable` Decorator
+
+```typescript
+import { traceable } from '@kyte/sdk';
+
+class MyService {
+  @traceable({ name: 'processData', type: 'chain' })
+  async processData(input: string) {
+    // Your code here - automatically traced!
+    return result;
+  }
+}
+```
+
+---
+
+## 📖 Usage Guide
+
+### Manual Tracing
+
+```typescript
+import { getKyte } from '@kyte/sdk';
+
+const kyte = getKyte();
+
+// Create a trace
+await kyte.trace('myOperation', async () => {
+  // Create child spans
+  const data = await kyte.span('fetchData', async () => {
+    return fetchDataFromDB();
+  });
+
+  const processed = await kyte.span('processData', async () => {
+    return processData(data);
+  });
+
+  return processed;
+});
+```
+
+### Decorator-Based Tracing
+
+```typescript
+import { traceable } from '@kyte/sdk';
+
+class OrderService {
+  @traceable({ name: 'createOrder', type: 'chain' })
+  async createOrder(userId: string, items: string[]) {
+    const user = await this.fetchUser(userId);
+    const total = await this.calculateTotal(items);
+    return { user, total };
+  }
+
+  @traceable({ type: 'tool' })
+  async fetchUser(userId: string) {
+    // Automatically becomes a span
+    return await db.users.findById(userId);
+  }
+
+  @traceable({ type: 'tool' })
+  async calculateTotal(items: string[]) {
+    // Another automatic span
+    return items.reduce((sum, item) => sum + item.price, 0);
+  }
+}
+```
+
+### OpenAI Integration
+
+```typescript
+import { wrapOpenAI } from '@kyte/sdk';
+import OpenAI from 'openai';
+
+const openai = wrapOpenAI(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));
+
+// All these calls are automatically traced with:
+// - Model name
+// - Token counts
+// - Cost calculation
+// - Latency tracking
+
+await openai.chat.completions.create({ /* ... */ });
+await openai.embeddings.create({ /* ... */ });
+```
+
+### Anthropic Integration
+
+```typescript
+import { wrapAnthropic } from '@kyte/sdk';
+import Anthropic from '@anthropic-ai/sdk';
+
+const anthropic = wrapAnthropic(new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }));
+
+// Auto-traced with full metrics
+await anthropic.messages.create({
+  model: 'claude-3-opus-20240229',
+  messages: [{ role: 'user', content: 'Hello!' }],
+});
+```
+
+### Session Tracking (Multi-Turn Conversations)
+
+```typescript
+const sessionId = 'user-123-conversation-456';
+
+// Turn 1
+await kyte.trace('turn1', async () => {
+  return 'Response 1';
+}, { sessionId });
+
+// Turn 2
+await kyte.trace('turn2', async () => {
+  return 'Response 2';
+}, { sessionId });
+
+// All traces are grouped in the same session!
+```
+
+### Adding Scores/Feedback
+
+```typescript
+await kyte.trace('generateResponse', async () => {
+  const response = generateResponse();
+
+  // Add quality score
+  const context = kyte.getCurrentContext();
+  if (context.traceId) {
+    await kyte.addScore(context.traceId, {
+      name: 'quality',
+      value: 0.95,
+      comment: 'High quality response',
+    });
+  }
+
+  return response;
+});
+```
+
+### Error Handling
+
+```typescript
+// Errors are automatically captured
+await kyte.trace('riskyOperation', async () => {
+  throw new Error('Something went wrong');
+  // Error is traced with full stack trace
+});
+```
+
+### Batching (Performance Optimization)
+
+```typescript
+initKyte({
+  apiUrl: 'https://your-kyte.com/api',
+  apiKey: 'your-key',
+  batchEnabled: true,      // Enable batching
+  batchSize: 10,           // Batch every 10 traces
+  batchTimeout: 1000,      // Or every 1 second
+});
+
+// Traces are now batched for better performance!
+```
+
+---
+
+## 🔧 Configuration
+
+### KyteConfig Options
+
+```typescript
+interface KyteConfig {
+  /** Kyte API endpoint URL (required) */
+  apiUrl: string;
+
+  /** API key for authentication (required) */
+  apiKey: string;
+
+  /** Project name for grouping traces */
+  projectName?: string;
+
+  /** Default tags to add to all traces */
+  defaultTags?: string[];
+
+  /** Default metadata to add to all traces */
+  defaultMetadata?: Record<string, any>;
+
+  /** Enable/disable tracing (default: true) */
+  enabled?: boolean;
+
+  /** Batch traces before sending (default: false) */
+  batchEnabled?: boolean;
+
+  /** Batch size (default: 10) */
+  batchSize?: number;
+
+  /** Batch timeout in milliseconds (default: 1000) */
+  batchTimeout?: number;
+}
+```
+
+### TraceableConfig Options
+
+```typescript
+interface TraceableConfig {
+  /** Name override for the trace/span */
+  name?: string;
+
+  /** Type override (llm, chain, tool, etc.) */
+  type?: SpanType;
+
+  /** Tags to add */
+  tags?: string[];
+
+  /** Metadata to add */
+  metadata?: Record<string, any>;
+
+  /** Capture function arguments as input (default: true) */
+  captureInput?: boolean;
+
+  /** Capture function output (default: true) */
+  captureOutput?: boolean;
+
+  /** Capture errors (default: true) */
+  captureErrors?: boolean;
+}
+```
+
+---
+
+## 🏗️ Architecture
+
+### Automatic Context Propagation
+
+Kyte uses Node.js's **AsyncLocalStorage** to automatically track parent-child relationships:
+
+```typescript
+await kyte.trace('parent', async () => {
+  // This automatically becomes a child span
+  await kyte.span('child1', async () => { /* ... */ });
+
+  // This too!
+  await kyte.span('child2', async () => { /* ... */ });
+});
+```
+
+No need to manually pass trace IDs around!
+
+### Dual Package Support
+
+The SDK works in both ESM and CommonJS projects:
+
+```typescript
+// ESM
+import { initKyte } from '@kyte/sdk';
+
+// CommonJS
+const { initKyte } = require('@kyte/sdk');
+```
+
+---
+
+## 🌐 Framework Integration
+
+### Next.js (App Router)
+
+```typescript
+// app/api/chat/route.ts
+import { initKyte, wrapOpenAI } from '@kyte/sdk';
+import OpenAI from 'openai';
+
+initKyte({
+  apiUrl: process.env.KYTE_API_URL!,
+  apiKey: process.env.KYTE_API_KEY!,
+  projectName: 'nextjs-app',
+});
+
+const openai = wrapOpenAI(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));
+
+export async function POST(req: Request) {
+  const { message } = await req.json();
+
+  const completion = await openai.chat.completions.create({
+    model: 'gpt-4',
+    messages: [{ role: 'user', content: message }],
+  });
+
+  return Response.json(completion);
+}
+```
+
+### Express.js
+
+```typescript
+import express from 'express';
+import { initKyte, getKyte } from '@kyte/sdk';
+
+initKyte({
+  apiUrl: process.env.KYTE_API_URL!,
+  apiKey: process.env.KYTE_API_KEY!,
+});
+
+const app = express();
+
+app.post('/api/process', async (req, res) => {
+  const kyte = getKyte();
+
+  const result = await kyte.trace('processRequest', async () => {
+    // Your processing logic
+    return processData(req.body);
+  });
+
+  res.json(result);
+});
+```
+
+### NestJS
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { traceable } from '@kyte/sdk';
+
+@Injectable()
+export class UserService {
+  @traceable({ name: 'getUser', type: 'tool' })
+  async getUser(id: string) {
+    return await this.userRepository.findById(id);
+  }
+
+  @traceable({ name: 'createUser', type: 'tool' })
+  async createUser(data: CreateUserDto) {
+    return await this.userRepository.create(data);
+  }
+}
+```
+
+---
+
+## 📊 Advanced Features
+
+### Kyte's Unique Capabilities
+
+Once you're using the SDK, you automatically get access to Kyte's advanced features:
+
+#### 1. **Autonomous Error Remediation**
+- Kyte automatically detects errors in your traces
+- Generates fixes using AI
+- Applies fixes to production
+- Monitors for success
+
+#### 2. **Proactive Error Prevention**
+- Analyzes patterns across all traces
+- Predicts potential failures
+- Alerts before errors occur
+
+#### 3. **Context Drift Detection**
+- Monitors multi-turn conversations
+- Detects when context is lost
+- Alerts when agent goes off-track
+
+#### 4. **Advanced Analytics**
+- Success rate by operation
+- Latency percentiles
+- Cost tracking
+- Token usage patterns
+
+---
+
+## 🧪 Testing
+
+```typescript
+import { initKyte, getKyte } from '@kyte/sdk';
+
+// Disable tracing in tests
+initKyte({
+  apiUrl: 'http://localhost:8000/api',
+  apiKey: 'test-key',
+  enabled: false,  // Tracing disabled
+});
+
+// Or enable/disable dynamically
+const kyte = getKyte();
+kyte.disable();  // Disable
+kyte.enable();   // Enable
+```
+
+---
+
+## 📚 Examples
+
+Check out the `/examples` directory:
+- `basic-usage.ts` - Core SDK features
+- `openai-example.ts` - OpenAI integration
+- `next-js-app/` - Full Next.js example
+- `express-api/` - Express.js example
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+---
+
+## 🔗 Links
+
+- **Website:** https://kyte.ai
+- **Documentation:** https://docs.kyte.ai
+- **GitHub:** https://github.com/kyte-ai/kyte
+- **NPM:** https://www.npmjs.com/package/@kyte/sdk
+
+---
+
+## 💬 Support
+
+- **Email:** support@kyte.ai
+- **Slack:** kyte-community.slack.com
+- **Issues:** https://github.com/kyte-ai/kyte/issues
+
+---
+
+**Built with ❤️ by the Kyte team**