teckel-ai 0.3.6 → 0.7.1

package/README.md

@@ -1,60 +1,72 @@
 # teckel-ai
 
-TypeScript/JavaScript SDK for [Teckel AI](https://teckel.ai)- Get insight into your AI systems, track topics of your choosing, and identify and fix knowledge gaps.
+TypeScript SDK for [Teckel AI](https://teckel.ai) an agentic monitoring platform for tracking behavior and improving AI output.
 
-## Installation
+## Install
 
 ```bash
 npm install teckel-ai
 ```
 
-**Requirements:** Node.js 18+ (or Bun, Deno, serverless runtimes)
-
 ## Quick Start
 
 ```typescript
 import { TeckelTracer } from 'teckel-ai';
 
-// Initialize once at startup
-const tracer = new TeckelTracer({
-  apiKey: process.env.TECKEL_API_KEY
+const tracer = new TeckelTracer({ apiKey: process.env.TECKEL_API_KEY });
+
+tracer.trace({
+  query: "How do I reset my password?",
+  response: "Go to Settings > Security...",
+  documents: [{ id: "doc-1", name: "Password Guide", text: "To reset..." }]
 });
 
-// In your API handler
-async function handleChat(userQuestion: string, sessionId: string) {
-  const conversation = tracer.start({ sessionRef: sessionId });
-
-  // Your existing RAG logic
-  const chunks = await vectorDB.search(userQuestion);
-  const answer = await llm.generate(userQuestion, chunks);
-
-  // Send trace (non-blocking)
-  conversation.trace({
-    query: userQuestion,
-    response: answer,
-    documents: chunks.map((chunk, i) => ({
-      documentRef: chunk.id,
-      documentName: chunk.title,
-      documentText: chunk.content,
-    }))
-  });
-
-  // For serverless: flush before returning
-  await conversation.flush();
-
-  return answer;
-}
+// Serverless: flush before returning
+await tracer.flush();
 ```
 
-## Documentation
+## OpenTelemetry Integration
+
+Capture detailed spans from AI SDK calls:
+
+```typescript
+import { TeckelTracer } from 'teckel-ai';
+import { TeckelSpanCollector } from 'teckel-ai/otel';
+
+const tracer = new TeckelTracer({ apiKey: process.env.TECKEL_API_KEY });
+const spanCollector = new TeckelSpanCollector();
+
+const result = await generateText({
+  model: openai('gpt-5-mini'),
+  prompt: userQuery,
+  experimental_telemetry: {
+    isEnabled: true,
+    tracer: spanCollector.getTracer()
+  }
+});
 
-- **Full SDK Reference:** [docs.teckel.ai/typescript-sdk-reference](https://docs.teckel.ai/typescript-sdk-reference)
-- **Getting Started:** [docs.teckel.ai/getting-started](https://docs.teckel.ai/getting-started)
+const spans = spanCollector.getSpans();
+
+// Tokens auto-aggregated from spans!
+tracer.trace({
+  query: userQuery,
+  response: result.text,
+  spans
+});
+
+await spanCollector.shutdown();
+```
+
+Requires: `npm install @opentelemetry/api @opentelemetry/sdk-trace-base`
+
+## Documentation
 
-## Support
+Full documentation at [docs.teckel.ai](https://docs.teckel.ai):
 
-- **Email:** support@teckel.ai
-- **Website:** [teckel.ai](https://teckel.ai)
+- [Getting Started](https://docs.teckel.ai/docs/getting_started)
+- [TypeScript SDK Reference](https://docs.teckel.ai/docs/typescript_sdk_reference)
+- [OpenTelemetry Integration](https://docs.teckel.ai/docs/opentelemetry_integration)
+- [HTTP API Reference](https://docs.teckel.ai/docs/http_api_reference)
 
 ## License