teckel-ai 0.3.6 → 0.7.1

package/dist/types-c7iVpo4d.d.mts

@@ -0,0 +1,177 @@
+/**
+ * Type definitions for teckel-ai SDK
+ */
+/**
+ * Configuration for batch trace ingestion
+ * Batching dramatically improves throughput (100x for high-volume scenarios)
+ */
+interface BatchConfig {
+    /** Maximum traces per batch (default: 100) */
+    maxSize?: number;
+    /** Maximum batch size in bytes (default: 5MB) */
+    maxBytes?: number;
+    /** Auto-flush interval in ms (default: 100ms) */
+    flushIntervalMs?: number;
+}
+interface TeckelConfig {
+    /** Teckel API key (tk_live_...) */
+    apiKey: string;
+    /** API endpoint (default: https://app.teckel.ai/api) */
+    endpoint?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Network timeout in ms (default: 5000) */
+    timeoutMs?: number;
+    /** Batch configuration for high-throughput ingestion */
+    batch?: BatchConfig;
+}
+/**
+ * Document/chunk from your RAG pipeline.
+ * The `id` field is your stable identifier - server generates internal UUIDs via deterministic hashing.
+ */
+interface Document {
+    /** Your document identifier (any format: "overview.md", "doc-123", etc.) */
+    id: string;
+    /** Human-readable document name */
+    name: string;
+    /** The actual text/chunk content */
+    text: string;
+    /** ISO 8601 timestamp - enables version tracking */
+    lastUpdated?: string;
+    /** Link to source (URL, intranet, file://) */
+    url?: string;
+    /** Storage platform: confluence, slack, gdrive, etc. */
+    source?: string;
+    /** File format: pdf, docx, md, etc. */
+    fileFormat?: string;
+    /** Vector similarity score (0-1) */
+    similarity?: number;
+    /** Position in results */
+    rank?: number;
+    /** Document owner email */
+    ownerEmail?: string;
+}
+interface TokenUsage {
+    prompt: number;
+    completion: number;
+    total: number;
+}
+/**
+ * Span type for tracing operations.
+ * Simplified to 6 meaningful operation types:
+ * - llm_call: LLM inference
+ * - tool_call: Tool/function execution
+ * - retrieval: RAG/knowledge retrieval
+ * - agent: Container for nested agent work
+ * - guardrail: Safety/validation checks
+ * - custom: Catch-all (default if not specified)
+ */
+type SpanType = 'llm_call' | 'tool_call' | 'retrieval' | 'agent' | 'guardrail' | 'custom';
+type SpanStatus = 'running' | 'completed' | 'error';
+/**
+ * Span data for tracing tool calls, LLM calls, and other operations.
+ * Enables waterfall visualization and detailed observability.
+ */
+interface SpanData {
+    /** Client-provided span ID (UUID, auto-generated if omitted) */
+    spanId?: string;
+    /** Parent span ID for nesting (references another span's spanId) */
+    parentSpanId?: string | null;
+    /** Span name (e.g., tool name, step description) */
+    name: string;
+    /** Type of span (optional, defaults to 'custom') */
+    type?: SpanType;
+    /** ISO 8601 start timestamp */
+    startedAt: string;
+    /** ISO 8601 end timestamp */
+    endedAt?: string | null;
+    /** Duration in milliseconds (auto-calculated if startedAt/endedAt provided) */
+    durationMs?: number;
+    /** Span status */
+    status?: SpanStatus;
+    /** Error message if status is 'error' */
+    statusMessage?: string | null;
+    /** Tool name (required for tool_call type) */
+    toolName?: string | null;
+    /** Tool arguments (max 500KB) */
+    toolArguments?: Record<string, unknown> | null;
+    /** Tool result (max 500KB) */
+    toolResult?: Record<string, unknown> | null;
+    /** Model name for llm_call type */
+    model?: string | null;
+    /** Prompt tokens for llm_call type */
+    promptTokens?: number | null;
+    /** Completion tokens for llm_call type */
+    completionTokens?: number | null;
+    /** Cost in USD for this span (optional: provide your own cost or let us calculate) */
+    costUsd?: number | null;
+    /** Generic input (max 500KB) */
+    input?: Record<string, unknown> | null;
+    /** Generic output (max 500KB) */
+    output?: Record<string, unknown> | null;
+    /** Custom metadata */
+    metadata?: Record<string, unknown> | null;
+}
+/**
+ * Trace data for a single query-response interaction.
+ * Sessions are created implicitly when traces share the same sessionId.
+ */
+interface TraceData {
+    /** User's question/prompt */
+    query: string;
+    /** LLM's response */
+    response: string;
+    /** Agent/function/workflow identifier (max 200 chars) */
+    agentName?: string | null;
+    /** Model name (e.g., 'gpt-5-mini') */
+    model?: string;
+    /** Response time in milliseconds */
+    latencyMs?: number;
+    /** Token usage */
+    tokens?: TokenUsage;
+    /** Cost in USD for this trace (optional: provide your own cost or let us calculate) */
+    costUsd?: number;
+    /** Source documents used in RAG */
+    documents?: Document[];
+    /** Spans for detailed tracing (tool calls, LLM calls, etc.) */
+    spans?: SpanData[];
+    /** Groups traces into a session (any string up to 200 chars, OTEL compatible) */
+    sessionId?: string;
+    /** User identifier */
+    userId?: string;
+    /** Client-provided trace ID (UUID, auto-generated if omitted) */
+    traceId?: string;
+    /** LLM system prompt/instructions */
+    systemPrompt?: string;
+    /** Custom metadata (max 10KB) */
+    metadata?: Record<string, unknown>;
+}
+type FeedbackType = 'thumbs_up' | 'thumbs_down' | 'flag' | 'rating';
+/**
+ * User feedback signal. Target either a specific trace or an entire session.
+ */
+interface FeedbackData {
+    /** Target trace (UUID) */
+    traceId?: string;
+    /** Target session (any string up to 200 chars) */
+    sessionId?: string;
+    /** Feedback type */
+    type: FeedbackType;
+    /** For ratings: '1'-'5' */
+    value?: string;
+    /** Optional comment */
+    comment?: string;
+}
+interface TraceResult {
+    traceId: string;
+    sessionId?: string;
+    chunkCount: number;
+}
+interface FeedbackResult {
+    feedbackId: string;
+    type: FeedbackType;
+    traceId?: string;
+    sessionId?: string;
+}
+
+export type { BatchConfig as B, Document as D, FeedbackData as F, SpanData as S, TeckelConfig as T, TraceData as a, TokenUsage as b, SpanType as c, SpanStatus as d, FeedbackType as e, TraceResult as f, FeedbackResult as g };

package/dist/types-c7iVpo4d.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Type definitions for teckel-ai SDK
+ */
+/**
+ * Configuration for batch trace ingestion
+ * Batching dramatically improves throughput (100x for high-volume scenarios)
+ */
+interface BatchConfig {
+    /** Maximum traces per batch (default: 100) */
+    maxSize?: number;
+    /** Maximum batch size in bytes (default: 5MB) */
+    maxBytes?: number;
+    /** Auto-flush interval in ms (default: 100ms) */
+    flushIntervalMs?: number;
+}
+interface TeckelConfig {
+    /** Teckel API key (tk_live_...) */
+    apiKey: string;
+    /** API endpoint (default: https://app.teckel.ai/api) */
+    endpoint?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Network timeout in ms (default: 5000) */
+    timeoutMs?: number;
+    /** Batch configuration for high-throughput ingestion */
+    batch?: BatchConfig;
+}
+/**
+ * Document/chunk from your RAG pipeline.
+ * The `id` field is your stable identifier - server generates internal UUIDs via deterministic hashing.
+ */
+interface Document {
+    /** Your document identifier (any format: "overview.md", "doc-123", etc.) */
+    id: string;
+    /** Human-readable document name */
+    name: string;
+    /** The actual text/chunk content */
+    text: string;
+    /** ISO 8601 timestamp - enables version tracking */
+    lastUpdated?: string;
+    /** Link to source (URL, intranet, file://) */
+    url?: string;
+    /** Storage platform: confluence, slack, gdrive, etc. */
+    source?: string;
+    /** File format: pdf, docx, md, etc. */
+    fileFormat?: string;
+    /** Vector similarity score (0-1) */
+    similarity?: number;
+    /** Position in results */
+    rank?: number;
+    /** Document owner email */
+    ownerEmail?: string;
+}
+interface TokenUsage {
+    prompt: number;
+    completion: number;
+    total: number;
+}
+/**
+ * Span type for tracing operations.
+ * Simplified to 6 meaningful operation types:
+ * - llm_call: LLM inference
+ * - tool_call: Tool/function execution
+ * - retrieval: RAG/knowledge retrieval
+ * - agent: Container for nested agent work
+ * - guardrail: Safety/validation checks
+ * - custom: Catch-all (default if not specified)
+ */
+type SpanType = 'llm_call' | 'tool_call' | 'retrieval' | 'agent' | 'guardrail' | 'custom';
+type SpanStatus = 'running' | 'completed' | 'error';
+/**
+ * Span data for tracing tool calls, LLM calls, and other operations.
+ * Enables waterfall visualization and detailed observability.
+ */
+interface SpanData {
+    /** Client-provided span ID (UUID, auto-generated if omitted) */
+    spanId?: string;
+    /** Parent span ID for nesting (references another span's spanId) */
+    parentSpanId?: string | null;
+    /** Span name (e.g., tool name, step description) */
+    name: string;
+    /** Type of span (optional, defaults to 'custom') */
+    type?: SpanType;
+    /** ISO 8601 start timestamp */
+    startedAt: string;
+    /** ISO 8601 end timestamp */
+    endedAt?: string | null;
+    /** Duration in milliseconds (auto-calculated if startedAt/endedAt provided) */
+    durationMs?: number;
+    /** Span status */
+    status?: SpanStatus;
+    /** Error message if status is 'error' */
+    statusMessage?: string | null;
+    /** Tool name (required for tool_call type) */
+    toolName?: string | null;
+    /** Tool arguments (max 500KB) */
+    toolArguments?: Record<string, unknown> | null;
+    /** Tool result (max 500KB) */
+    toolResult?: Record<string, unknown> | null;
+    /** Model name for llm_call type */
+    model?: string | null;
+    /** Prompt tokens for llm_call type */
+    promptTokens?: number | null;
+    /** Completion tokens for llm_call type */
+    completionTokens?: number | null;
+    /** Cost in USD for this span (optional: provide your own cost or let us calculate) */
+    costUsd?: number | null;
+    /** Generic input (max 500KB) */
+    input?: Record<string, unknown> | null;
+    /** Generic output (max 500KB) */
+    output?: Record<string, unknown> | null;
+    /** Custom metadata */
+    metadata?: Record<string, unknown> | null;
+}
+/**
+ * Trace data for a single query-response interaction.
+ * Sessions are created implicitly when traces share the same sessionId.
+ */
+interface TraceData {
+    /** User's question/prompt */
+    query: string;
+    /** LLM's response */
+    response: string;
+    /** Agent/function/workflow identifier (max 200 chars) */
+    agentName?: string | null;
+    /** Model name (e.g., 'gpt-5-mini') */
+    model?: string;
+    /** Response time in milliseconds */
+    latencyMs?: number;
+    /** Token usage */
+    tokens?: TokenUsage;
+    /** Cost in USD for this trace (optional: provide your own cost or let us calculate) */
+    costUsd?: number;
+    /** Source documents used in RAG */
+    documents?: Document[];
+    /** Spans for detailed tracing (tool calls, LLM calls, etc.) */
+    spans?: SpanData[];
+    /** Groups traces into a session (any string up to 200 chars, OTEL compatible) */
+    sessionId?: string;
+    /** User identifier */
+    userId?: string;
+    /** Client-provided trace ID (UUID, auto-generated if omitted) */
+    traceId?: string;
+    /** LLM system prompt/instructions */
+    systemPrompt?: string;
+    /** Custom metadata (max 10KB) */
+    metadata?: Record<string, unknown>;
+}
+type FeedbackType = 'thumbs_up' | 'thumbs_down' | 'flag' | 'rating';
+/**
+ * User feedback signal. Target either a specific trace or an entire session.
+ */
+interface FeedbackData {
+    /** Target trace (UUID) */
+    traceId?: string;
+    /** Target session (any string up to 200 chars) */
+    sessionId?: string;
+    /** Feedback type */
+    type: FeedbackType;
+    /** For ratings: '1'-'5' */
+    value?: string;
+    /** Optional comment */
+    comment?: string;
+}
+interface TraceResult {
+    traceId: string;
+    sessionId?: string;
+    chunkCount: number;
+}
+interface FeedbackResult {
+    feedbackId: string;
+    type: FeedbackType;
+    traceId?: string;
+    sessionId?: string;
+}
+
+export type { BatchConfig as B, Document as D, FeedbackData as F, SpanData as S, TeckelConfig as T, TraceData as a, TokenUsage as b, SpanType as c, SpanStatus as d, FeedbackType as e, TraceResult as f, FeedbackResult as g };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "teckel-ai",
-  "version": "0.3.6",
-  "description": "Simple SDK for AI conversation tracking and RAG observability",
+  "version": "0.7.1",
+  "description": "Simple SDK for AI trace tracking and RAG observability",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -15,6 +15,16 @@
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
       }
+    },
+    "./otel": {
+      "import": {
+        "types": "./dist/otel/index.d.mts",
+        "default": "./dist/otel/index.mjs"
+      },
+      "require": {
+        "types": "./dist/otel/index.d.ts",
+        "default": "./dist/otel/index.js"
+      }
     }
   },
   "files": [
@@ -25,7 +35,10 @@
     "build": "tsup",
     "clean": "rm -rf dist",
     "prepublishOnly": "npm run clean && npm run build",
-    "type-check": "tsc --noEmit"
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --exclude tests/integration.test.ts",
+    "test:watch": "vitest --exclude tests/integration.test.ts",
+    "test:integration": "vitest run tests/integration.test.ts"
   },
   "keywords": [
     "llm",
@@ -35,7 +48,9 @@
     "audit",
     "trace",
     "observability",
-    "teckel"
+    "teckel",
+    "opentelemetry",
+    "otel"
   ],
   "author": "Teckel AI",
   "license": "MIT",
@@ -46,9 +61,24 @@
   "dependencies": {
     "zod": "^3.23.8"
   },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/sdk-trace-base": "^1.25.0 || ^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-trace-base": {
+      "optional": true
+    }
+  },
   "devDependencies": {
-    "tsup": "^8.3.5",
-    "typescript": "^5.0.0"
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/sdk-trace-base": "^2.5.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.0.0",
+    "vitest": "^2.1.0"
   },
   "homepage": "https://teckel.ai",
   "bugs": {