teckel-ai 0.3.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Teckel 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,53 @@
+# teckel-ai
+
+## What is Teckel AI?
+
+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.
+
+**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.
+
+**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.
+
+## What This SDK Does
+
+This lightweight SDK (one dependency, 20-minute integration) sends your AI conversations to Teckel for analysis. You get:
+
+- **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
+
+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.
+
+## Getting Started
+
+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)
+
+## Documentation
+
+- [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
+
+## Requirements
+
+- Node.js 18+ (or Bun, Deno, serverless runtimes)
+- A Teckel AI account with API key
+- An LLM-based application (RAG system, chatbot, AI agent)
+
+## Support
+
+- **Documentation**: [docs.teckel.ai](https://docs.teckel.ai)
+- **Dashboard**: [app.teckel.ai](https://app.teckel.ai)
+- **Email**: support@teckel.ai
+
+## License
+
+MIT
+
+---
+
+Version 0.3.2

package/dist/conversation.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Conversation class for teckel-ai SDK v0.3.1
+ * Manages a single conversation with fire-and-forget semantics
+ */
+import type { TraceData, FeedbackData, ConversationOptions, TraceResult } from './types';
+export declare class Conversation {
+    private readonly apiKey;
+    private readonly endpoint;
+    private readonly sessionRef;
+    private readonly userId?;
+    private readonly metadata?;
+    private readonly startedAt;
+    private readonly debug;
+    private readonly timeoutMs;
+    private turnCount;
+    private startPromise;
+    private sendQueue;
+    constructor(apiKey: string, endpoint: string, options: ConversationOptions, 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;
+    /**
+     * Synchronous trace: waits for HTTP send to complete.
+     * Throws on network/validation errors.
+     * Respects send queue to maintain trace ordering.
+     */
+    traceSync(data: TraceData, opt?: {
+        timeoutMs?: number;
+    }): Promise<TraceResult>;
+    /**
+     * 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>;
+    private mapOTelAliases;
+}

package/dist/conversation.js

@@ -0,0 +1,363 @@
+"use strict";
+/**
+ * Conversation class for teckel-ai SDK v0.3.1
+ * Manages a single conversation with fire-and-forget semantics
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Conversation = void 0;
+const schemas_1 = require("./schemas");
+class Conversation {
+    constructor(apiKey, endpoint, options, debug = false, extras = { timeoutMs: 5000 }) {
+        this.turnCount = 0;
+        this.sendQueue = Promise.resolve();
+        this.apiKey = apiKey;
+        this.endpoint = endpoint;
+        this.sessionRef = options.sessionRef;
+        this.userId = options.userId;
+        this.metadata = options.metadata;
+        this.startedAt = new Date();
+        this.debug = debug;
+        this.timeoutMs = extras.timeoutMs;
+        if (this.debug) {
+            console.log('[Teckel] Conversation started:', {
+                sessionRef: this.sessionRef,
+                userId: this.userId
+            });
+        }
+        // Start conversation and store promise
+        this.startPromise = this._startConversation().catch(err => {
+            if (this.debug) {
+                console.warn('[Teckel] Start failed:', err.message);
+            }
+        });
+    }
+    /**
+     * Record a trace (single query-response interaction)
+     * Fire-and-forget by default - never blocks
+     * For serverless, call flush() before function termination
+     */
+    trace(data) {
+        var _a;
+        try {
+            // Validate with Zod
+            const validated = schemas_1.TraceDataSchema.parse(data);
+            // Apply OTel alias mapping (beta): infer canonical fields from metadata if missing
+            const mapped = this.mapOTelAliases(validated);
+            // Increment local turn number immediately (client-side counter)
+            const localTurn = ++this.turnCount;
+            // Ensure we have a client-provided traceRef; if missing, generate a deterministic one
+            const finalTraceRef = mapped.traceRef && mapped.traceRef.length > 0
+                ? mapped.traceRef
+                : `${this.sessionRef}:${localTurn}`;
+            if (this.debug) {
+                console.log('[Teckel] Queueing trace (fire-and-forget):', {
+                    sessionRef: this.sessionRef,
+                    turnNumber: localTurn,
+                    queryLength: mapped.query.length,
+                    responseLength: mapped.response.length,
+                    documentCount: ((_a = mapped.documents) === null || _a === void 0 ? void 0 : _a.length) || 0
+                });
+            }
+            const toSend = Object.assign(Object.assign({}, mapped), { traceRef: finalTraceRef });
+            // Fire-and-forget: enqueue and return immediately
+            this.enqueueSend(async () => {
+                try {
+                    await this.startPromise; // ensure conversation exists
+                    await this._sendTrace(toSend);
+                }
+                catch (err) {
+                    if (this.debug) {
+                        console.warn('[Teckel] Trace send failed (non-blocking):', (err === null || err === void 0 ? void 0 : err.message) || err);
+                    }
+                }
+            });
+            return { traceRef: finalTraceRef, turnNumber: localTurn };
+        }
+        catch (err) {
+            // Validation failed - log and continue (never throw to user)
+            if (this.debug) {
+                console.warn('[Teckel] Invalid trace data:', err);
+            }
+        }
+    }
+    /**
+     * Synchronous trace: waits for HTTP send to complete.
+     * Throws on network/validation errors.
+     * Respects send queue to maintain trace ordering.
+     */
+    async traceSync(data, opt) {
+        // Validate with Zod
+        const validated = schemas_1.TraceDataSchema.parse(data);
+        // Apply OTel alias mapping
+        const mapped = this.mapOTelAliases(validated);
+        // Increment local turn and compute final traceRef
+        const localTurn = ++this.turnCount;
+        const finalTraceRef = mapped.traceRef && mapped.traceRef.length > 0
+            ? mapped.traceRef
+            : `${this.sessionRef}:${localTurn}`;
+        const toSend = Object.assign(Object.assign({}, mapped), { traceRef: finalTraceRef });
+        try {
+            await this.startPromise;
+            // Wait for any queued operations to complete first (maintains ordering)
+            await this.sendQueue.catch(() => { });
+            await this._sendTrace(toSend, { timeoutMs: opt === null || opt === void 0 ? void 0 : opt.timeoutMs });
+            return { traceRef: finalTraceRef, turnNumber: localTurn };
+        }
+        catch (err) {
+            if (this.debug) {
+                console.warn('[Teckel] Sync trace failed:', (err === null || err === void 0 ? void 0 : err.message) || err);
+            }
+            throw err;
+        }
+    }
+    /**
+     * Add user feedback signal
+     * Never throws - gracefully handles errors
+     */
+    async feedback(data) {
+        try {
+            // Validate with Zod
+            const validated = schemas_1.FeedbackDataSchema.parse(data);
+            if (this.debug) {
+                console.log('[Teckel] Sending feedback:', {
+                    sessionRef: this.sessionRef,
+                    type: validated.type
+                });
+            }
+            // Enqueue feedback so flush() covers it in serverless
+            this.enqueueSend(async () => {
+                try {
+                    await this._sendFeedback(validated);
+                }
+                catch (err) {
+                    if (this.debug) {
+                        console.warn('[Teckel] Feedback failed:', (err === null || err === void 0 ? void 0 : err.message) || err);
+                    }
+                }
+            });
+        }
+        catch (err) {
+            // Validation failed - log and continue
+            if (this.debug) {
+                console.warn('[Teckel] Invalid feedback data:', err);
+            }
+        }
+    }
+    /**
+     * End the conversation
+     * Flushes all pending traces before sending end signal
+     * Never throws - gracefully handles errors
+     */
+    async end() {
+        const duration = Date.now() - this.startedAt.getTime();
+        if (this.debug) {
+            console.log('[Teckel] Ending conversation:', {
+                sessionRef: this.sessionRef,
+                durationMs: duration,
+                turnCount: this.turnCount
+            });
+        }
+        // Enqueue end so it occurs after any pending sends
+        this.enqueueSend(async () => {
+            try {
+                await this._endConversation(duration);
+            }
+            catch (err) {
+                if (this.debug) {
+                    console.warn('[Teckel] End failed:', (err === null || err === void 0 ? void 0 : err.message) || err);
+                }
+            }
+        });
+        // Flush queue (serverless-safe)
+        await this.flush();
+    }
+    /**
+     * Read-only properties
+     */
+    get id() {
+        return this.sessionRef;
+    }
+    get turns() {
+        return this.turnCount;
+    }
+    get started() {
+        return this.startedAt;
+    }
+    // Private HTTP methods
+    // Lightweight fetch with a single retry on transient errors (429/5xx or network)
+    async fetchWithRetry(url, init, opts) {
+        var _a, _b;
+        const retries = (_a = opts === null || opts === void 0 ? void 0 : opts.retries) !== null && _a !== void 0 ? _a : 1;
+        const retryDelayMs = (_b = opts === null || opts === void 0 ? void 0 : opts.retryDelayMs) !== null && _b !== void 0 ? _b : 250;
+        let attempt = 0;
+        // Simple jittered delay
+        const sleep = (ms) => new Promise(res => setTimeout(res, ms));
+        // We reuse the same init; AbortSignal.timeout recreates a fresh signal per call
+        while (true) {
+            try {
+                const response = await fetch(url, init);
+                if (!response.ok && (response.status === 429 || (response.status >= 500 && response.status <= 599))) {
+                    if (attempt < retries) {
+                        attempt++;
+                        if (this.debug)
+                            console.warn('[Teckel] HTTP retry', { url, status: response.status, attempt });
+                        await sleep(retryDelayMs + Math.floor(Math.random() * 100));
+                        continue;
+                    }
+                }
+                return response;
+            }
+            catch (err) {
+                if (attempt < retries) {
+                    attempt++;
+                    if (this.debug)
+                        console.warn('[Teckel] Network retry', { url, attempt, error: err instanceof Error ? err.message : String(err) });
+                    await sleep(retryDelayMs + Math.floor(Math.random() * 100));
+                    continue;
+                }
+                throw err;
+            }
+        }
+    }
+    async _startConversation() {
+        const response = await this.fetchWithRetry(`${this.endpoint}/conversations`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json'
+            },
+            keepalive: true,
+            signal: AbortSignal.timeout ? AbortSignal.timeout(this.timeoutMs) : undefined,
+            body: JSON.stringify({
+                sessionRef: this.sessionRef,
+                userId: this.userId,
+                metadata: this.metadata
+            })
+        }, { retries: 1, retryDelayMs: 300 });
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+    }
+    async _sendTrace(data, opt) {
+        var _a;
+        const response = await this.fetchWithRetry(`${this.endpoint}/conversations/${this.sessionRef}/traces`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json'
+            },
+            keepalive: true,
+            signal: AbortSignal.timeout ? AbortSignal.timeout((_a = opt === null || opt === void 0 ? void 0 : opt.timeoutMs) !== null && _a !== void 0 ? _a : this.timeoutMs) : undefined,
+            body: JSON.stringify(data)
+        }, { retries: 1, retryDelayMs: 300 });
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+        const result = await response.json();
+        return result;
+    }
+    async _sendFeedback(data) {
+        const response = await this.fetchWithRetry(`${this.endpoint}/conversations/${this.sessionRef}/feedback`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json'
+            },
+            keepalive: true,
+            signal: AbortSignal.timeout ? AbortSignal.timeout(this.timeoutMs) : undefined,
+            body: JSON.stringify(data)
+        }, { retries: 1, retryDelayMs: 300 });
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+    }
+    async _endConversation(duration) {
+        const response = await this.fetchWithRetry(`${this.endpoint}/conversations/${this.sessionRef}`, {
+            method: 'PATCH',
+            headers: {
+                'Authorization': `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json'
+            },
+            keepalive: true,
+            signal: AbortSignal.timeout ? AbortSignal.timeout(this.timeoutMs) : undefined,
+            body: JSON.stringify({
+                durationMs: duration,
+                turnCount: this.turnCount
+            })
+        }, { retries: 1, retryDelayMs: 300 });
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+    }
+    // Utility: append a send task to the queue
+    enqueueSend(task) {
+        this.sendQueue = this.sendQueue.then(() => task()).catch(() => {
+            // Errors are handled where task is defined; keep queue alive
+        });
+    }
+    /**
+     * Flush queued sends with a bounded timeout.
+     * Returns when the queue is empty or the timeout elapses (whichever comes first).
+     */
+    async flush(timeoutMs) {
+        const waitMs = (typeof timeoutMs === 'number' && Number.isFinite(timeoutMs) && timeoutMs >= 0)
+            ? timeoutMs
+            : this.timeoutMs;
+        // Snapshot current queue to cover all work up to this call
+        const done = this.sendQueue.catch(() => { });
+        let timer;
+        try {
+            await Promise.race([
+                done,
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error('Flush timeout')), waitMs);
+                })
+            ]);
+        }
+        catch (err) {
+            if (this.debug) {
+                console.warn('[Teckel] Flush incomplete:', (err === null || err === void 0 ? void 0 : err.message) || err);
+            }
+            // Surface timeout so callers can react in serverless
+            throw err;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    // Utility: map OpenTelemetry-like metadata to canonical fields (beta)
+    mapOTelAliases(data) {
+        try {
+            const meta = data.metadata;
+            if (!meta)
+                return data;
+            const mapped = Object.assign({}, data);
+            // Model
+            if (!mapped.model && typeof meta['gen_ai.request.model'] === 'string') {
+                mapped.model = meta['gen_ai.request.model'];
+            }
+            // Tokens
+            const inTok = meta['gen_ai.usage.input_tokens'];
+            const outTok = meta['gen_ai.usage.output_tokens'];
+            const totTok = meta['gen_ai.usage.total_tokens'];
+            if (!mapped.tokens && (typeof inTok === 'number' || typeof outTok === 'number')) {
+                mapped.tokens = {
+                    prompt: typeof inTok === 'number' ? inTok : 0,
+                    completion: typeof outTok === 'number' ? outTok : 0,
+                    total: typeof totTok === 'number' ? totTok : ((typeof inTok === 'number' ? inTok : 0) + (typeof outTok === 'number' ? outTok : 0))
+                };
+            }
+            // Latency
+            const latency = meta['gen_ai.response.latency'];
+            if (!mapped.responseTimeMs && typeof latency === 'number') {
+                mapped.responseTimeMs = latency;
+            }
+            return mapped;
+        }
+        catch (_a) {
+            return data;
+        }
+    }
+}
+exports.Conversation = Conversation;

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * teckel-ai v0.3.1
+ * Simple SDK for AI conversation tracking and RAG observability
+ *
+ * @packageDocumentation
+ */
+export { TeckelTracer } from './tracer';
+export { Conversation } from './conversation';
+export type { TeckelConfig, ConversationOptions, TraceData, Document, TokenUsage, FeedbackData, FeedbackType, ValidationResult, TraceResult } from './types';
+export { TeckelConfigSchema, ConversationOptionsSchema, TraceDataSchema, DocumentSchema, TokenUsageSchema, FeedbackDataSchema } from './schemas';

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * teckel-ai v0.3.1
+ * Simple SDK for AI conversation tracking and RAG observability
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FeedbackDataSchema = exports.TokenUsageSchema = exports.DocumentSchema = exports.TraceDataSchema = exports.ConversationOptionsSchema = exports.TeckelConfigSchema = exports.Conversation = exports.TeckelTracer = void 0;
+// Main SDK exports
+var tracer_1 = require("./tracer");
+Object.defineProperty(exports, "TeckelTracer", { enumerable: true, get: function () { return tracer_1.TeckelTracer; } });
+var conversation_1 = require("./conversation");
+Object.defineProperty(exports, "Conversation", { enumerable: true, get: function () { return conversation_1.Conversation; } });
+// Schema exports (for advanced use cases)
+var schemas_1 = require("./schemas");
+Object.defineProperty(exports, "TeckelConfigSchema", { enumerable: true, get: function () { return schemas_1.TeckelConfigSchema; } });
+Object.defineProperty(exports, "ConversationOptionsSchema", { enumerable: true, get: function () { return schemas_1.ConversationOptionsSchema; } });
+Object.defineProperty(exports, "TraceDataSchema", { enumerable: true, get: function () { return schemas_1.TraceDataSchema; } });
+Object.defineProperty(exports, "DocumentSchema", { enumerable: true, get: function () { return schemas_1.DocumentSchema; } });
+Object.defineProperty(exports, "TokenUsageSchema", { enumerable: true, get: function () { return schemas_1.TokenUsageSchema; } });
+Object.defineProperty(exports, "FeedbackDataSchema", { enumerable: true, get: function () { return schemas_1.FeedbackDataSchema; } });

package/dist/schemas.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Zod validation schemas for teckel-ai SDK v0.3.1
+ */
+import { z } from 'zod';
+/**
+ * Document schema
+ */
+export declare const DocumentSchema: z.ZodObject<{
+    documentRef: z.ZodString;
+    documentName: z.ZodString;
+    documentText: z.ZodString;
+    documentLastUpdated: z.ZodOptional<z.ZodString>;
+    sourceUri: z.ZodOptional<z.ZodString>;
+    sourceType: z.ZodOptional<z.ZodString>;
+    similarity: z.ZodOptional<z.ZodNumber>;
+    rank: z.ZodOptional<z.ZodNumber>;
+    ownerEmail: z.ZodOptional<z.ZodString>;
+    documentType: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    documentRef: string;
+    documentName: string;
+    documentText: string;
+    documentLastUpdated?: string | undefined;
+    sourceUri?: string | undefined;
+    sourceType?: string | undefined;
+    similarity?: number | undefined;
+    rank?: number | undefined;
+    ownerEmail?: string | undefined;
+    documentType?: string | undefined;
+}, {
+    documentRef: string;
+    documentName: string;
+    documentText: string;
+    documentLastUpdated?: string | undefined;
+    sourceUri?: string | undefined;
+    sourceType?: string | undefined;
+    similarity?: number | undefined;
+    rank?: number | undefined;
+    ownerEmail?: string | undefined;
+    documentType?: string | undefined;
+}>;
+/**
+ * Token usage schema
+ */
+export declare const TokenUsageSchema: z.ZodObject<{
+    prompt: z.ZodNumber;
+    completion: z.ZodNumber;
+    total: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    prompt: number;
+    completion: number;
+    total: number;
+}, {
+    prompt: number;
+    completion: number;
+    total: number;
+}>;
+/**
+ * Trace data schema
+ */
+export declare const TraceDataSchema: z.ZodObject<{
+    query: z.ZodString;
+    response: z.ZodString;
+    model: z.ZodOptional<z.ZodString>;
+    responseTimeMs: z.ZodOptional<z.ZodNumber>;
+    documents: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        documentRef: z.ZodString;
+        documentName: z.ZodString;
+        documentText: z.ZodString;
+        documentLastUpdated: z.ZodOptional<z.ZodString>;
+        sourceUri: z.ZodOptional<z.ZodString>;
+        sourceType: z.ZodOptional<z.ZodString>;
+        similarity: z.ZodOptional<z.ZodNumber>;
+        rank: z.ZodOptional<z.ZodNumber>;
+        ownerEmail: z.ZodOptional<z.ZodString>;
+        documentType: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        documentRef: string;
+        documentName: string;
+        documentText: string;
+        documentLastUpdated?: string | undefined;
+        sourceUri?: string | undefined;
+        sourceType?: string | undefined;
+        similarity?: number | undefined;
+        rank?: number | undefined;
+        ownerEmail?: string | undefined;
+        documentType?: string | undefined;
+    }, {
+        documentRef: string;
+        documentName: string;
+        documentText: string;
+        documentLastUpdated?: string | undefined;
+        sourceUri?: string | undefined;
+        sourceType?: string | undefined;
+        similarity?: number | undefined;
+        rank?: number | undefined;
+        ownerEmail?: string | undefined;
+        documentType?: string | undefined;
+    }>, "many">>;
+    tokens: z.ZodOptional<z.ZodObject<{
+        prompt: z.ZodNumber;
+        completion: z.ZodNumber;
+        total: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        prompt: number;
+        completion: number;
+        total: number;
+    }, {
+        prompt: number;
+        completion: number;
+        total: number;
+    }>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    traceRef: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    response: string;
+    model?: string | undefined;
+    responseTimeMs?: number | undefined;
+    documents?: {
+        documentRef: string;
+        documentName: string;
+        documentText: string;
+        documentLastUpdated?: string | undefined;
+        sourceUri?: string | undefined;
+        sourceType?: string | undefined;
+        similarity?: number | undefined;
+        rank?: number | undefined;
+        ownerEmail?: string | undefined;
+        documentType?: string | undefined;
+    }[] | undefined;
+    tokens?: {
+        prompt: number;
+        completion: number;
+        total: number;
+    } | undefined;
+    metadata?: Record<string, any> | undefined;
+    traceRef?: string | undefined;
+}, {
+    query: string;
+    response: string;
+    model?: string | undefined;
+    responseTimeMs?: number | undefined;
+    documents?: {
+        documentRef: string;
+        documentName: string;
+        documentText: string;
+        documentLastUpdated?: string | undefined;
+        sourceUri?: string | undefined;
+        sourceType?: string | undefined;
+        similarity?: number | undefined;
+        rank?: number | undefined;
+        ownerEmail?: string | undefined;
+        documentType?: string | undefined;
+    }[] | undefined;
+    tokens?: {
+        prompt: number;
+        completion: number;
+        total: number;
+    } | undefined;
+    metadata?: Record<string, any> | undefined;
+    traceRef?: 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>>;
+}, "strip", z.ZodTypeAny, {
+    sessionRef: string;
+    metadata?: Record<string, any> | undefined;
+    userId?: string | undefined;
+}, {
+    sessionRef: string;
+    metadata?: Record<string, any> | undefined;
+    userId?: string | undefined;
+}>;
+/**
+ * Feedback data schema
+ */
+export declare const FeedbackDataSchema: z.ZodObject<{
+    type: z.ZodEnum<["thumbs_up", "thumbs_down", "flag", "rating"]>;
+    value: z.ZodOptional<z.ZodString>;
+    comment: z.ZodOptional<z.ZodString>;
+    traceRef: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "thumbs_up" | "thumbs_down" | "flag" | "rating";
+    value?: string | undefined;
+    traceRef?: string | undefined;
+    comment?: string | undefined;
+}, {
+    type: "thumbs_up" | "thumbs_down" | "flag" | "rating";
+    value?: string | undefined;
+    traceRef?: string | undefined;
+    comment?: string | undefined;
+}>;
+/**
+ * Config schema
+ */
+export declare const TeckelConfigSchema: z.ZodObject<{
+    apiKey: z.ZodString;
+    endpoint: z.ZodOptional<z.ZodString>;
+    debug: z.ZodOptional<z.ZodBoolean>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    apiKey: string;
+    endpoint?: string | undefined;
+    debug?: boolean | undefined;
+    timeoutMs?: number | undefined;
+}, {
+    apiKey: string;
+    endpoint?: string | undefined;
+    debug?: boolean | undefined;
+    timeoutMs?: number | undefined;
+}>;

package/dist/schemas.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Zod validation schemas for teckel-ai SDK v0.3.1
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TeckelConfigSchema = exports.FeedbackDataSchema = exports.ConversationOptionsSchema = exports.TraceDataSchema = exports.TokenUsageSchema = exports.DocumentSchema = void 0;
+const zod_1 = require("zod");
+/**
+ * Document schema
+ */
+exports.DocumentSchema = zod_1.z.object({
+    documentRef: zod_1.z.string().min(1, 'documentRef is required'),
+    documentName: zod_1.z.string().min(1, 'documentName is required'),
+    documentText: zod_1.z.string().min(1, 'documentText is required'),
+    documentLastUpdated: zod_1.z.string().optional(),
+    sourceUri: zod_1.z.string().optional(),
+    sourceType: zod_1.z.string().optional(),
+    similarity: zod_1.z.number().min(0).max(1).optional(),
+    rank: zod_1.z.number().int().nonnegative().optional(),
+    ownerEmail: zod_1.z.string().email().optional(),
+    documentType: zod_1.z.string().optional()
+});
+/**
+ * Token usage schema
+ */
+exports.TokenUsageSchema = zod_1.z.object({
+    prompt: zod_1.z.number().int().nonnegative(),
+    completion: zod_1.z.number().int().nonnegative(),
+    total: zod_1.z.number().int().nonnegative()
+});
+/**
+ * Trace data schema
+ */
+exports.TraceDataSchema = zod_1.z.object({
+    query: zod_1.z.string().min(1, 'query is required').max(10000, 'query too long (max 10,000 characters)'),
+    response: zod_1.z.string().min(1, 'response is required').max(50000, 'response too long (max 50,000 characters)'),
+    model: zod_1.z.string().optional(),
+    responseTimeMs: zod_1.z.number().positive().optional(),
+    documents: zod_1.z.array(exports.DocumentSchema).max(50, 'Too many documents (max 50)').optional(),
+    tokens: exports.TokenUsageSchema.optional(),
+    metadata: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional(),
+    traceRef: zod_1.z.string().min(1).optional()
+});
+/**
+ * Conversation options schema
+ */
+exports.ConversationOptionsSchema = zod_1.z.object({
+    sessionRef: zod_1.z.string().min(1, 'sessionRef is required'),
+    userId: zod_1.z.string().optional(),
+    metadata: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional()
+});
+/**
+ * Feedback data schema
+ */
+exports.FeedbackDataSchema = zod_1.z.object({
+    type: zod_1.z.enum(['thumbs_up', 'thumbs_down', 'flag', 'rating']),
+    value: zod_1.z.string().optional(),
+    comment: zod_1.z.string().optional(),
+    traceRef: zod_1.z.string().optional()
+});
+/**
+ * Config schema
+ */
+exports.TeckelConfigSchema = zod_1.z.object({
+    apiKey: zod_1.z.string().min(1, 'apiKey is required'),
+    endpoint: zod_1.z.string().url().optional(),
+    debug: zod_1.z.boolean().optional(),
+    timeoutMs: zod_1.z.number().int().positive().max(60000).optional()
+});

package/dist/tracer.d.ts

@@ -0,0 +1,18 @@
+/**
+ * TeckelTracer - Main SDK class for teckel-ai v0.3.1
+ * Simple, lightweight SDK for AI conversation tracking
+ */
+import { Conversation } from './conversation';
+import type { TeckelConfig, ConversationOptions } from './types';
+export 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 (sessionId is legacy alias)
+     */
+    start(options: ConversationOptions): Conversation;
+}

package/dist/tracer.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * TeckelTracer - Main SDK class for teckel-ai v0.3.1
+ * Simple, lightweight SDK for AI conversation tracking
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TeckelTracer = void 0;
+const conversation_1 = require("./conversation");
+const schemas_1 = require("./schemas");
+class TeckelTracer {
+    constructor(config) {
+        // Validate config with Zod
+        const validated = schemas_1.TeckelConfigSchema.parse(config);
+        // API key format warning
+        if (!validated.apiKey.startsWith('tk_live_')) {
+            console.warn('[Teckel] API key should start with "tk_live_". ' +
+                'Current key: ' + validated.apiKey.substring(0, 10) + '...');
+        }
+        this.apiKey = validated.apiKey;
+        this.endpoint = validated.endpoint || 'https://app.teckel.ai/api';
+        this.debug = validated.debug || false;
+        // Default timeout mirrors common telemetry SDKs (3–5s) to tolerate cold starts
+        this.timeoutMs = typeof validated.timeoutMs === 'number' ? validated.timeoutMs : 5000;
+        if (this.debug) {
+            console.log('[Teckel] SDK initialized:', {
+                endpoint: this.endpoint,
+                version: '0.3.1',
+                timeoutMs: this.timeoutMs
+            });
+        }
+    }
+    /**
+     * Start a new conversation
+     * sessionRef IS the public conversation identifier (sessionId is legacy alias)
+     */
+    start(options) {
+        // Validate options with Zod
+        const validated = schemas_1.ConversationOptionsSchema.parse(options);
+        // Create and return conversation instance
+        return new conversation_1.Conversation(this.apiKey, this.endpoint, validated, this.debug, {
+            timeoutMs: this.timeoutMs
+        });
+    }
+}
+exports.TeckelTracer = TeckelTracer;

package/dist/types.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Type definitions for teckel-ai SDK v0.3.1
+ * Simple, clean types matching existing database schema
+ */
+/**
+ * SDK Configuration
+ */
+export interface TeckelConfig {
+    apiKey: string;
+    endpoint?: string;
+    debug?: boolean;
+    timeoutMs?: number;
+}
+/**
+ * Conversation options
+ * sessionId IS the conversation identifier
+ */
+export interface ConversationOptions {
+    sessionRef: string;
+    userId?: string;
+    metadata?: Record<string, any>;
+}
+/**
+ * Document structure for RAG systems
+ * Matches existing documents + chunk_events schema
+ */
+export 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
+ */
+export interface TokenUsage {
+    prompt: number;
+    completion: number;
+    total: number;
+}
+/**
+ * Trace data for a single query-response interaction
+ * Matches existing traces table schema
+ */
+export interface TraceData {
+    query: string;
+    response: string;
+    model?: string;
+    responseTimeMs?: number;
+    documents?: Document[];
+    tokens?: TokenUsage;
+    metadata?: Record<string, any>;
+    traceRef?: string;
+}
+/**
+ * Feedback types
+ */
+export type FeedbackType = 'thumbs_up' | 'thumbs_down' | 'flag' | 'rating';
+/**
+ * User feedback signal
+ */
+export interface FeedbackData {
+    type: FeedbackType;
+    value?: string;
+    comment?: string;
+    traceRef?: string;
+}
+/**
+ * Result returned when a trace is created
+ */
+export interface TraceResult {
+    traceRef: string;
+    turnNumber: number;
+}
+/**
+ * Validation result structure
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Type definitions for teckel-ai SDK v0.3.1
+ * Simple, clean types matching existing database schema
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "teckel-ai",
+  "version": "0.3.2",
+  "description": "Simple SDK for AI conversation tracking and RAG observability",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "llm",
+    "rag",
+    "monitoring",
+    "ai",
+    "audit",
+    "trace",
+    "observability",
+    "teckel"
+  ],
+  "author": "Teckel AI",
+  "license": "MIT",
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/spencine/AI-Audit-Tool.git",
+    "directory": "packages/tracer"
+  },
+  "homepage": "https://teckel.ai",
+  "bugs": {
+    "url": "https://github.com/spencine/AI-Audit-Tool/issues"
+  }
+}