teckel-ai 0.3.2 → 0.3.5

package/README.md

@@ -1,53 +1,61 @@
 # teckel-ai
 
-## What is 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.
 
-Teckel AI helps you understand and improve your AI chatbots by analyzing conversations your users are having. We track what questions users ask, how well your AI answers them, and tell you which areas needs improvement.
+## Installation
 
-**Your Problem**: Your RAG or MCP referencing AI chat system gives incomplete or incorrect answers because your knowledge base has gaps. Users get frustrated, support tickets increase, and you don't know which areas to focus on.
+```bash
+npm install teckel-ai
+```
 
-**Our Service**: We analyze every AI response for accuracy and completeness, cluster similar queries to identify trending topics (or let you define an area of interest and see related questions), and tell you exactly which AI-retrieved documentation to add or update, prioritized by impact. We write your document templates for you to fill in with info your users need, and give you updates on your AI system's health via Slack.
+**Requirements:** Node.js 18+ (or Bun, Deno, serverless runtimes)
 
-## What This SDK Does
+## Quick Start
 
-This lightweight SDK (one dependency, 20-minute integration) sends your AI conversations to Teckel for analysis. You get:
+```typescript
+import { TeckelTracer } from 'teckel-ai';
 
-- **Completeness Scoring** - How well each response answers the user's question (0-100%)
-- **Accuracy Analysis** - Whether AI claims are supported by your source documents
-- **Topic Intelligence** - Automatic clustering of queries to reveal documentation gaps
-- **Actionable Feedback** - Specific recommendations on what knowledge your AI needs to better answer user questions
+// Initialize once at startup
+const tracer = new TeckelTracer({
+  apiKey: process.env.TECKEL_API_KEY
+});
 
-Works with any RAG system or AI conversational framework: LangChain, LlamaIndex, Vercel AI SDK, custom implementations using vector database retrieval, or direct OpenAI/Anthropic calls.
+// In your API handler
+async function handleChat(userQuestion: string, sessionId: string) {
+  const conversation = tracer.start({ sessionRef: sessionId });
 
-## Getting Started
+  // Your existing RAG logic
+  const chunks = await vectorDB.search(userQuestion);
+  const answer = await llm.generate(userQuestion, chunks);
 
-1. **Sign up** at [app.teckel.ai](https://app.teckel.ai) with a 14 day free trial
-2. **Generate an API key** from your dashboard (Admin Panel > API Keys)
-3. **Install the SDK**: `npm install teckel-ai`
-4. **Follow the integration guide** at [docs.teckel.ai/docs/getting-started](https://docs.teckel.ai/docs/getting-started)
+  // Send trace (non-blocking)
+  conversation.trace({
+    query: userQuestion,
+    response: answer,
+    documents: chunks.map((chunk, i) => ({
+      documentRef: chunk.id,
+      documentName: chunk.title,
+      documentText: chunk.content,
+    }))
+  });
 
-## Documentation
+  // For serverless: flush before returning
+  await conversation.flush();
 
-- [Getting Started Guide](https://docs.teckel.ai/docs/getting-started) - Step-by-step integration
-- [API & SDK Reference](https://docs.teckel.ai/docs/api-sdk-reference) - Complete field documentation and framework examples
-- [Troubleshooting](https://docs.teckel.ai/docs/troubleshooting) - Common issues and solutions
+  return answer;
+}
+```
 
-## Requirements
+## Documentation
 
-- Node.js 18+ (or Bun, Deno, serverless runtimes)
-- A Teckel AI account with API key
-- An LLM-based application (RAG system, chatbot, AI agent)
+- **Full SDK Reference:** [docs.teckel.ai/docs/typescript-sdk-reference](https://docs.teckel.ai/docs/typescript-sdk-reference)
+- **Getting Started:** [docs.teckel.ai/docs/getting-started](https://docs.teckel.ai/docs/getting-started)
 
 ## Support
 
-- **Documentation**: [docs.teckel.ai](https://docs.teckel.ai)
-- **Dashboard**: [app.teckel.ai](https://app.teckel.ai)
-- **Email**: support@teckel.ai
+- **Email:** support@teckel.ai
+- **Website** [teckel.ai](https://teckel.ai)
 
 ## License
 
 MIT
-
----
-
-Version 0.3.2

package/dist/{schemas.d.ts → index.d.mts}

@@ -1,11 +1,178 @@
+import { z } from 'zod';
+
 /**
- * Zod validation schemas for teckel-ai SDK v0.3.1
+ * Type definitions for teckel-ai SDK v0.3.5
+ * Simple, clean types matching existing database schema
  */
-import { z } from 'zod';
+/**
+ * SDK Configuration
+ */
+interface TeckelConfig {
+    apiKey: string;
+    endpoint?: string;
+    debug?: boolean;
+    timeoutMs?: number;
+}
+/**
+ * Conversation options
+ * sessionRef IS the conversation identifier
+ *
+ * Naming convention:
+ * - *Ref = Client-provided identifier (TEXT)
+ * - *Id = Server-generated internal ID (UUID)
+ */
+interface ConversationOptions {
+    sessionRef?: string;
+    userRef?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Document structure for RAG systems
+ * Matches existing documents + chunk_events schema
+ */
+interface Document {
+    documentRef: string;
+    documentName: string;
+    documentText: string;
+    documentLastUpdated?: string;
+    sourceUri?: string;
+    sourceType?: string;
+    similarity?: number;
+    rank?: number;
+    ownerEmail?: string;
+    documentType?: string;
+}
+/**
+ * Token usage tracking
+ */
+interface TokenUsage {
+    prompt: number;
+    completion: number;
+    total: number;
+}
+/**
+ * Trace data for a single query-response interaction
+ * Matches existing traces table schema
+ */
+interface TraceData {
+    query: string;
+    response: string;
+    model?: string;
+    responseTimeMs?: number;
+    documents?: Document[];
+    tokens?: TokenUsage;
+    metadata?: Record<string, unknown>;
+    traceRef?: string;
+    userRef?: string;
+}
+/**
+ * Feedback types
+ */
+type FeedbackType = 'thumbs_up' | 'thumbs_down' | 'flag' | 'rating';
+/**
+ * User feedback signal
+ */
+interface FeedbackData {
+    type: FeedbackType;
+    value?: string;
+    comment?: string;
+    traceRef?: string;
+}
+/**
+ * Result returned when a trace is created
+ */
+interface TraceResult {
+    traceRef: string;
+    turnNumber: number;
+}
+
+/**
+ * Conversation class for teckel-ai SDK v0.3.5
+ * Manages a single conversation with fire-and-forget semantics
+ */
+
+/** Internal type - sessionRef is guaranteed by TeckelTracer.start() */
+interface ResolvedConversationOptions extends ConversationOptions {
+    sessionRef: string;
+}
+declare class Conversation {
+    private readonly apiKey;
+    private readonly endpoint;
+    private readonly sessionRef;
+    private readonly userRef?;
+    private readonly metadata?;
+    private readonly startedAt;
+    private readonly debug;
+    private readonly timeoutMs;
+    private turnCount;
+    private startPromise;
+    private sendQueue;
+    constructor(apiKey: string, endpoint: string, options: ResolvedConversationOptions, debug?: boolean, extras?: {
+        timeoutMs: number;
+    });
+    /**
+     * Record a trace (single query-response interaction)
+     * Fire-and-forget by default - never blocks
+     * For serverless, call flush() before function termination
+     */
+    trace(data: TraceData): TraceResult | void;
+    /**
+     * Add user feedback signal
+     * Never throws - gracefully handles errors
+     */
+    feedback(data: FeedbackData): Promise<void>;
+    /**
+     * End the conversation
+     * Flushes all pending traces before sending end signal
+     * Never throws - gracefully handles errors
+     */
+    end(): Promise<void>;
+    /**
+     * Read-only properties
+     */
+    get id(): string;
+    get turns(): number;
+    get started(): Date;
+    private fetchWithRetry;
+    private _startConversation;
+    private _sendTrace;
+    private _sendFeedback;
+    private _endConversation;
+    private enqueueSend;
+    /**
+     * Flush queued sends with a bounded timeout.
+     * Returns when the queue is empty or the timeout elapses (whichever comes first).
+     */
+    flush(timeoutMs?: number): Promise<void>;
+}
+
+/**
+ * TeckelTracer - Main SDK class for teckel-ai v0.3.5
+ * Simple, lightweight SDK for AI conversation tracking
+ */
+
+declare class TeckelTracer {
+    private readonly apiKey;
+    private readonly endpoint;
+    private readonly debug;
+    private readonly timeoutMs;
+    constructor(config: TeckelConfig);
+    /**
+     * Start a new conversation
+     * sessionRef IS the public conversation identifier
+     * If not provided, auto-generates one as 'auto:{8-char-uuid}'
+     */
+    start(options?: ConversationOptions): Conversation;
+}
+
+/**
+ * Zod validation schemas for teckel-ai SDK v0.3.5
+ */
+
 /**
  * Document schema
  */
-export declare const DocumentSchema: z.ZodObject<{
+declare const DocumentSchema: z.ZodObject<{
     documentRef: z.ZodString;
     documentName: z.ZodString;
     documentText: z.ZodString;
@@ -42,7 +209,7 @@ export declare const DocumentSchema: z.ZodObject<{
 /**
  * Token usage schema
  */
-export declare const TokenUsageSchema: z.ZodObject<{
+declare const TokenUsageSchema: z.ZodObject<{
     prompt: z.ZodNumber;
     completion: z.ZodNumber;
     total: z.ZodNumber;
@@ -58,7 +225,7 @@ export declare const TokenUsageSchema: z.ZodObject<{
 /**
  * Trace data schema
  */
-export declare const TraceDataSchema: z.ZodObject<{
+declare const TraceDataSchema: z.ZodObject<{
     query: z.ZodString;
     response: z.ZodString;
     model: z.ZodOptional<z.ZodString>;
@@ -110,8 +277,9 @@ export declare const TraceDataSchema: z.ZodObject<{
         completion: number;
         total: number;
     }>>;
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     traceRef: z.ZodOptional<z.ZodString>;
+    userRef: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     query: string;
     response: string;
@@ -134,8 +302,9 @@ export declare const TraceDataSchema: z.ZodObject<{
         completion: number;
         total: number;
     } | undefined;
-    metadata?: Record<string, any> | undefined;
+    metadata?: Record<string, unknown> | undefined;
     traceRef?: string | undefined;
+    userRef?: string | undefined;
 }, {
     query: string;
     response: string;
@@ -158,29 +327,30 @@ export declare const TraceDataSchema: z.ZodObject<{
         completion: number;
         total: number;
     } | undefined;
-    metadata?: Record<string, any> | undefined;
+    metadata?: Record<string, unknown> | undefined;
     traceRef?: string | undefined;
+    userRef?: string | undefined;
 }>;
 /**
  * Conversation options schema
  */
-export declare const ConversationOptionsSchema: z.ZodObject<{
-    sessionRef: z.ZodString;
-    userId: z.ZodOptional<z.ZodString>;
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+declare const ConversationOptionsSchema: z.ZodObject<{
+    sessionRef: z.ZodOptional<z.ZodString>;
+    userRef: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
-    sessionRef: string;
-    metadata?: Record<string, any> | undefined;
-    userId?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    userRef?: string | undefined;
+    sessionRef?: string | undefined;
 }, {
-    sessionRef: string;
-    metadata?: Record<string, any> | undefined;
-    userId?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    userRef?: string | undefined;
+    sessionRef?: string | undefined;
 }>;
 /**
  * Feedback data schema
  */
-export declare const FeedbackDataSchema: z.ZodObject<{
+declare const FeedbackDataSchema: z.ZodObject<{
     type: z.ZodEnum<["thumbs_up", "thumbs_down", "flag", "rating"]>;
     value: z.ZodOptional<z.ZodString>;
     comment: z.ZodOptional<z.ZodString>;
@@ -199,7 +369,7 @@ export declare const FeedbackDataSchema: z.ZodObject<{
 /**
  * Config schema
  */
-export declare const TeckelConfigSchema: z.ZodObject<{
+declare const TeckelConfigSchema: z.ZodObject<{
     apiKey: z.ZodString;
     endpoint: z.ZodOptional<z.ZodString>;
     debug: z.ZodOptional<z.ZodBoolean>;
@@ -215,3 +385,5 @@ export declare const TeckelConfigSchema: z.ZodObject<{
     debug?: boolean | undefined;
     timeoutMs?: number | undefined;
 }>;
+
+export { Conversation, type ConversationOptions, ConversationOptionsSchema, type Document, DocumentSchema, type FeedbackData, FeedbackDataSchema, type FeedbackType, type TeckelConfig, TeckelConfigSchema, TeckelTracer, type TokenUsage, TokenUsageSchema, type TraceData, TraceDataSchema, type TraceResult };