@kayba_ai/tracing 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,85 @@
+import * as mlflow_tracing from 'mlflow-tracing';
+import { SpanType } from 'mlflow-tracing';
+export { LiveSpan, Span, SpanType } from 'mlflow-tracing';
+
+interface ConfigureOptions {
+    /** Kayba API key. Falls back to `KAYBA_API_KEY` env var. */
+    apiKey?: string;
+    /** Kayba API base URL. Falls back to `KAYBA_API_URL` env var, then `https://use.kayba.ai`. */
+    baseUrl?: string;
+    /** Alias for `folder`. If both provided, `folder` takes precedence. */
+    experiment?: string;
+    /** Folder name for organizing traces in the Kayba dashboard. */
+    folder?: string;
+    /** MLflow experiment ID. Defaults to `"0"`. */
+    experimentId?: string;
+}
+interface TraceOptions {
+    /** Custom span name. Defaults to the function name. */
+    name?: string;
+    /** Span type (e.g. SpanType.LLM, SpanType.AGENT). */
+    spanType?: SpanType;
+    /** Additional span attributes. */
+    attributes?: Record<string, unknown>;
+}
+interface StartSpanOptions {
+    /** Span name. */
+    name: string;
+    /** Span type. */
+    spanType?: SpanType;
+    /** Input data to attach to the span. */
+    inputs?: Record<string, unknown>;
+}
+/**
+ * Configure Kayba tracing.
+ *
+ * Sets the MLflow tracking URI and authentication so that all
+ * subsequent `trace` / `startSpan` calls export to Kayba.
+ */
+declare function configure(options?: ConfigureOptions): void;
+/**
+ * Change the target folder for subsequent traces.
+ *
+ * @param folder - Folder name, or `null` to clear (traces go to Unfiled).
+ */
+declare function setFolder(folder: string | null): void;
+/** Return the currently configured folder, or `null`. */
+declare function getFolder(): string | null;
+/**
+ * Wrap a function with tracing. The returned function generates a span
+ * each time it is called, with automatic folder tagging.
+ *
+ * @example
+ * ```ts
+ * const myFunc = trace(async (input: string) => {
+ *   return doWork(input);
+ * }, { name: "my_func", spanType: SpanType.LLM });
+ * ```
+ */
+declare function trace<T extends (...args: any[]) => any>(fn: T, options?: TraceOptions): T;
+/**
+ * Create a span manually. Call `.end()` when done.
+ *
+ * @example
+ * ```ts
+ * const span = startSpan({ name: "retrieval", spanType: SpanType.TOOL });
+ * span.setInputs({ query });
+ * // ... work ...
+ * span.end({ outputs: { result }, status: "OK" });
+ * ```
+ */
+declare function startSpan(options: StartSpanOptions): mlflow_tracing.LiveSpan;
+/** Returns whether `configure()` has been called. */
+declare function isConfigured(): boolean;
+
+declare const kayba: {
+    configure: typeof configure;
+    trace: typeof trace;
+    startSpan: typeof startSpan;
+    setFolder: typeof setFolder;
+    getFolder: typeof getFolder;
+    isConfigured: typeof isConfigured;
+    SpanType: typeof SpanType;
+};
+
+export { type ConfigureOptions, type StartSpanOptions, type TraceOptions, configure, kayba as default, getFolder, isConfigured, setFolder, startSpan, trace };

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+import * as mlflow_tracing from 'mlflow-tracing';
+import { SpanType } from 'mlflow-tracing';
+export { LiveSpan, Span, SpanType } from 'mlflow-tracing';
+
+interface ConfigureOptions {
+    /** Kayba API key. Falls back to `KAYBA_API_KEY` env var. */
+    apiKey?: string;
+    /** Kayba API base URL. Falls back to `KAYBA_API_URL` env var, then `https://use.kayba.ai`. */
+    baseUrl?: string;
+    /** Alias for `folder`. If both provided, `folder` takes precedence. */
+    experiment?: string;
+    /** Folder name for organizing traces in the Kayba dashboard. */
+    folder?: string;
+    /** MLflow experiment ID. Defaults to `"0"`. */
+    experimentId?: string;
+}
+interface TraceOptions {
+    /** Custom span name. Defaults to the function name. */
+    name?: string;
+    /** Span type (e.g. SpanType.LLM, SpanType.AGENT). */
+    spanType?: SpanType;
+    /** Additional span attributes. */
+    attributes?: Record<string, unknown>;
+}
+interface StartSpanOptions {
+    /** Span name. */
+    name: string;
+    /** Span type. */
+    spanType?: SpanType;
+    /** Input data to attach to the span. */
+    inputs?: Record<string, unknown>;
+}
+/**
+ * Configure Kayba tracing.
+ *
+ * Sets the MLflow tracking URI and authentication so that all
+ * subsequent `trace` / `startSpan` calls export to Kayba.
+ */
+declare function configure(options?: ConfigureOptions): void;
+/**
+ * Change the target folder for subsequent traces.
+ *
+ * @param folder - Folder name, or `null` to clear (traces go to Unfiled).
+ */
+declare function setFolder(folder: string | null): void;
+/** Return the currently configured folder, or `null`. */
+declare function getFolder(): string | null;
+/**
+ * Wrap a function with tracing. The returned function generates a span
+ * each time it is called, with automatic folder tagging.
+ *
+ * @example
+ * ```ts
+ * const myFunc = trace(async (input: string) => {
+ *   return doWork(input);
+ * }, { name: "my_func", spanType: SpanType.LLM });
+ * ```
+ */
+declare function trace<T extends (...args: any[]) => any>(fn: T, options?: TraceOptions): T;
+/**
+ * Create a span manually. Call `.end()` when done.
+ *
+ * @example
+ * ```ts
+ * const span = startSpan({ name: "retrieval", spanType: SpanType.TOOL });
+ * span.setInputs({ query });
+ * // ... work ...
+ * span.end({ outputs: { result }, status: "OK" });
+ * ```
+ */
+declare function startSpan(options: StartSpanOptions): mlflow_tracing.LiveSpan;
+/** Returns whether `configure()` has been called. */
+declare function isConfigured(): boolean;
+
+declare const kayba: {
+    configure: typeof configure;
+    trace: typeof trace;
+    startSpan: typeof startSpan;
+    setFolder: typeof setFolder;
+    getFolder: typeof getFolder;
+    isConfigured: typeof isConfigured;
+    SpanType: typeof SpanType;
+};
+
+export { type ConfigureOptions, type StartSpanOptions, type TraceOptions, configure, kayba as default, getFolder, isConfigured, setFolder, startSpan, trace };

package/dist/index.js

@@ -0,0 +1,143 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  SpanType: () => import_mlflow_tracing2.SpanType,
+  configure: () => configure,
+  default: () => index_default,
+  getFolder: () => getFolder,
+  isConfigured: () => isConfigured,
+  setFolder: () => setFolder,
+  startSpan: () => startSpan,
+  trace: () => trace
+});
+module.exports = __toCommonJS(index_exports);
+var import_mlflow_tracing = require("mlflow-tracing");
+var import_mlflow_tracing2 = require("mlflow-tracing");
+var DEFAULT_BASE_URL = "https://use.kayba.ai";
+var MAX_FOLDER_LENGTH = 256;
+var SAFE_FOLDER_RE = /[^a-zA-Z0-9 _\-/.]/g;
+var HTML_TAG_RE = /<[^>]*>/g;
+var _folder = null;
+var _configured = false;
+function sanitizeFolder(name) {
+  let clean = name.replace(HTML_TAG_RE, "");
+  clean = clean.replace(SAFE_FOLDER_RE, "");
+  return clean.trim().slice(0, MAX_FOLDER_LENGTH);
+}
+function resolveFolder(folder, experiment) {
+  const raw = folder ?? experiment;
+  if (!raw) return null;
+  const sanitized = sanitizeFolder(raw);
+  return sanitized || null;
+}
+function injectFolderTag() {
+  if (_folder !== null) {
+    try {
+      (0, import_mlflow_tracing.updateCurrentTrace)({ tags: { "kayba.folder": _folder } });
+    } catch {
+    }
+  }
+}
+function configure(options = {}) {
+  const apiKey = options.apiKey || process.env.KAYBA_API_KEY || "";
+  if (!apiKey) {
+    throw new Error(
+      "No API key provided. Pass apiKey or set the KAYBA_API_KEY environment variable."
+    );
+  }
+  const baseUrl = options.baseUrl || process.env.KAYBA_API_URL || DEFAULT_BASE_URL;
+  const trackingUri = baseUrl.replace(/\/+$/, "") + "/api/mlflow";
+  process.env.MLFLOW_TRACKING_TOKEN = apiKey;
+  process.env.MLFLOW_TRACKING_URI = trackingUri;
+  const experimentId = options.experimentId || process.env.MLFLOW_EXPERIMENT_ID || "0";
+  (0, import_mlflow_tracing.init)({ trackingUri, experimentId });
+  _folder = resolveFolder(options.folder, options.experiment);
+  _configured = true;
+}
+function setFolder(folder) {
+  if (folder === null) {
+    _folder = null;
+  } else {
+    const sanitized = sanitizeFolder(folder);
+    _folder = sanitized || null;
+  }
+}
+function getFolder() {
+  return _folder;
+}
+function trace(fn, options = {}) {
+  const fnWithTag = (...args) => {
+    const result = fn(...args);
+    if (result instanceof Promise) {
+      return result.then((value) => {
+        injectFolderTag();
+        return value;
+      });
+    }
+    injectFolderTag();
+    return result;
+  };
+  const mlflowOptions = {};
+  if (options.name) mlflowOptions.name = options.name;
+  if (options.spanType) mlflowOptions.spanType = options.spanType;
+  if (options.attributes)
+    mlflowOptions.attributes = options.attributes;
+  return (0, import_mlflow_tracing.trace)(fnWithTag, mlflowOptions);
+}
+function startSpan(options) {
+  const mlflowOptions = {
+    name: options.name
+  };
+  if (options.spanType) mlflowOptions.spanType = options.spanType;
+  if (options.inputs) mlflowOptions.inputs = options.inputs;
+  const span = (0, import_mlflow_tracing.startSpan)(mlflowOptions);
+  const originalEnd = span.end.bind(span);
+  span.end = (endOptions) => {
+    injectFolderTag();
+    return originalEnd(endOptions);
+  };
+  return span;
+}
+function isConfigured() {
+  return _configured;
+}
+var kayba = {
+  configure,
+  trace,
+  startSpan,
+  setFolder,
+  getFolder,
+  isConfigured,
+  SpanType: import_mlflow_tracing.SpanType
+};
+var index_default = kayba;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SpanType,
+  configure,
+  getFolder,
+  isConfigured,
+  setFolder,
+  startSpan,
+  trace
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * Kayba tracing SDK for TypeScript/Node.js.\n *\n * Thin wrapper around `mlflow-tracing` that configures auth and\n * injects Kayba-specific folder tags.\n *\n * @example\n * ```ts\n * import kayba from \"@kayba_ai/tracing\";\n *\n * kayba.configure({\n *   apiKey: process.env.KAYBA_API_KEY,\n *   folder: \"my-project\",\n * });\n *\n * const myAgent = kayba.trace(async (topic: string) => {\n *   const span = kayba.startSpan({ name: \"retrieval\" });\n *   // ... work ...\n *   span.end({ status: \"OK\" });\n *   return result;\n * }, { name: \"research_agent\" });\n * ```\n */\n\nimport {\n  init,\n  trace as mlflowTrace,\n  startSpan as mlflowStartSpan,\n  updateCurrentTrace,\n  SpanType,\n  type TraceOptions as MlflowTraceOptions,\n  type SpanOptions as MlflowSpanOptions,\n} from \"mlflow-tracing\";\n\n// ── Constants ──────────────────────────────────────────────────────────\n\nconst DEFAULT_BASE_URL = \"https://use.kayba.ai\";\nconst MAX_FOLDER_LENGTH = 256;\nconst SAFE_FOLDER_RE = /[^a-zA-Z0-9 _\\-/.]/g;\nconst HTML_TAG_RE = /<[^>]*>/g;\n\n// ── Module state ───────────────────────────────────────────────────────\n\nlet _folder: string | null = null;\nlet _configured = false;\n\n// ── Types ──────────────────────────────────────────────────────────────\n\nexport interface ConfigureOptions {\n  /** Kayba API key. Falls back to `KAYBA_API_KEY` env var. */\n  apiKey?: string;\n  /** Kayba API base URL. Falls back to `KAYBA_API_URL` env var, then `https://use.kayba.ai`. */\n  baseUrl?: string;\n  /** Alias for `folder`. If both provided, `folder` takes precedence. */\n  experiment?: string;\n  /** Folder name for organizing traces in the Kayba dashboard. */\n  folder?: string;\n  /** MLflow experiment ID. Defaults to `\"0\"`. */\n  experimentId?: string;\n}\n\nexport interface TraceOptions {\n  /** Custom span name. Defaults to the function name. */\n  name?: string;\n  /** Span type (e.g. SpanType.LLM, SpanType.AGENT). */\n  spanType?: SpanType;\n  /** Additional span attributes. */\n  attributes?: Record<string, unknown>;\n}\n\nexport interface StartSpanOptions {\n  /** Span name. */\n  name: string;\n  /** Span type. */\n  spanType?: SpanType;\n  /** Input data to attach to the span. */\n  inputs?: Record<string, unknown>;\n}\n\n// ── Internal helpers ───────────────────────────────────────────────────\n\nfunction sanitizeFolder(name: string): string {\n  let clean = name.replace(HTML_TAG_RE, \"\");\n  clean = clean.replace(SAFE_FOLDER_RE, \"\");\n  return clean.trim().slice(0, MAX_FOLDER_LENGTH);\n}\n\nfunction resolveFolder(\n  folder: string | undefined,\n  experiment: string | undefined,\n): string | null {\n  const raw = folder ?? experiment;\n  if (!raw) return null;\n  const sanitized = sanitizeFolder(raw);\n  return sanitized || null;\n}\n\nfunction injectFolderTag(): void {\n  if (_folder !== null) {\n    try {\n      updateCurrentTrace({ tags: { \"kayba.folder\": _folder } });\n    } catch {\n      // Silently ignore if no active trace context.\n    }\n  }\n}\n\n// ── Public API ─────────────────────────────────────────────────────────\n\n/**\n * Configure Kayba tracing.\n *\n * Sets the MLflow tracking URI and authentication so that all\n * subsequent `trace` / `startSpan` calls export to Kayba.\n */\nexport function configure(options: ConfigureOptions = {}): void {\n  const apiKey = options.apiKey || process.env.KAYBA_API_KEY || \"\";\n\n  if (!apiKey) {\n    throw new Error(\n      \"No API key provided. Pass apiKey or set the KAYBA_API_KEY environment variable.\",\n    );\n  }\n\n  const baseUrl =\n    options.baseUrl || process.env.KAYBA_API_URL || DEFAULT_BASE_URL;\n\n  const trackingUri = baseUrl.replace(/\\/+$/, \"\") + \"/api/mlflow\";\n\n  // Configure MLflow under the hood.\n  process.env.MLFLOW_TRACKING_TOKEN = apiKey;\n  process.env.MLFLOW_TRACKING_URI = trackingUri;\n\n  const experimentId =\n    options.experimentId || process.env.MLFLOW_EXPERIMENT_ID || \"0\";\n\n  init({ trackingUri, experimentId });\n\n  _folder = resolveFolder(options.folder, options.experiment);\n  _configured = true;\n}\n\n/**\n * Change the target folder for subsequent traces.\n *\n * @param folder - Folder name, or `null` to clear (traces go to Unfiled).\n */\nexport function setFolder(folder: string | null): void {\n  if (folder === null) {\n    _folder = null;\n  } else {\n    const sanitized = sanitizeFolder(folder);\n    _folder = sanitized || null;\n  }\n}\n\n/** Return the currently configured folder, or `null`. */\nexport function getFolder(): string | null {\n  return _folder;\n}\n\n/**\n * Wrap a function with tracing. The returned function generates a span\n * each time it is called, with automatic folder tagging.\n *\n * @example\n * ```ts\n * const myFunc = trace(async (input: string) => {\n *   return doWork(input);\n * }, { name: \"my_func\", spanType: SpanType.LLM });\n * ```\n */\nexport function trace<T extends (...args: any[]) => any>(\n  fn: T,\n  options: TraceOptions = {},\n): T {\n  // Wrap the function to inject the folder tag after execution.\n  const fnWithTag = (...args: Parameters<T>): ReturnType<T> => {\n    const result = fn(...args);\n\n    // Handle async functions: inject tag after the promise resolves.\n    if (result instanceof Promise) {\n      return result.then((value: unknown) => {\n        injectFolderTag();\n        return value;\n      }) as ReturnType<T>;\n    }\n\n    injectFolderTag();\n    return result;\n  };\n\n  const mlflowOptions: MlflowTraceOptions = {};\n  if (options.name) mlflowOptions.name = options.name;\n  if (options.spanType) mlflowOptions.spanType = options.spanType;\n  if (options.attributes)\n    mlflowOptions.attributes = options.attributes as Record<string, any>;\n\n  return mlflowTrace(fnWithTag as T, mlflowOptions);\n}\n\n/**\n * Create a span manually. Call `.end()` when done.\n *\n * @example\n * ```ts\n * const span = startSpan({ name: \"retrieval\", spanType: SpanType.TOOL });\n * span.setInputs({ query });\n * // ... work ...\n * span.end({ outputs: { result }, status: \"OK\" });\n * ```\n */\nexport function startSpan(options: StartSpanOptions) {\n  const mlflowOptions: MlflowSpanOptions = {\n    name: options.name,\n  };\n  if (options.spanType) mlflowOptions.spanType = options.spanType;\n  if (options.inputs) mlflowOptions.inputs = options.inputs;\n\n  const span = mlflowStartSpan(mlflowOptions);\n\n  // Wrap .end() to inject the folder tag before closing.\n  const originalEnd = span.end.bind(span);\n  span.end = (endOptions?: Parameters<typeof span.end>[0]) => {\n    injectFolderTag();\n    return originalEnd(endOptions);\n  };\n\n  return span;\n}\n\n/** Returns whether `configure()` has been called. */\nexport function isConfigured(): boolean {\n  return _configured;\n}\n\n// ── Re-export MLflow types for convenience ─────────────────────────────\n\nexport { SpanType } from \"mlflow-tracing\";\nexport type { LiveSpan, Span } from \"mlflow-tracing\";\n\n// ── Default export ─────────────────────────────────────────────────────\n\nconst kayba = {\n  configure,\n  trace,\n  startSpan,\n  setFolder,\n  getFolder,\n  isConfigured,\n  SpanType,\n};\n\nexport default kayba;\n"],"mappings":"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","names":["import_mlflow_tracing","mlflowTrace","mlflowStartSpan"]}

package/dist/index.mjs

@@ -0,0 +1,118 @@
+// src/index.ts
+import {
+  init,
+  trace as mlflowTrace,
+  startSpan as mlflowStartSpan,
+  updateCurrentTrace,
+  SpanType
+} from "mlflow-tracing";
+import { SpanType as SpanType2 } from "mlflow-tracing";
+var DEFAULT_BASE_URL = "https://use.kayba.ai";
+var MAX_FOLDER_LENGTH = 256;
+var SAFE_FOLDER_RE = /[^a-zA-Z0-9 _\-/.]/g;
+var HTML_TAG_RE = /<[^>]*>/g;
+var _folder = null;
+var _configured = false;
+function sanitizeFolder(name) {
+  let clean = name.replace(HTML_TAG_RE, "");
+  clean = clean.replace(SAFE_FOLDER_RE, "");
+  return clean.trim().slice(0, MAX_FOLDER_LENGTH);
+}
+function resolveFolder(folder, experiment) {
+  const raw = folder ?? experiment;
+  if (!raw) return null;
+  const sanitized = sanitizeFolder(raw);
+  return sanitized || null;
+}
+function injectFolderTag() {
+  if (_folder !== null) {
+    try {
+      updateCurrentTrace({ tags: { "kayba.folder": _folder } });
+    } catch {
+    }
+  }
+}
+function configure(options = {}) {
+  const apiKey = options.apiKey || process.env.KAYBA_API_KEY || "";
+  if (!apiKey) {
+    throw new Error(
+      "No API key provided. Pass apiKey or set the KAYBA_API_KEY environment variable."
+    );
+  }
+  const baseUrl = options.baseUrl || process.env.KAYBA_API_URL || DEFAULT_BASE_URL;
+  const trackingUri = baseUrl.replace(/\/+$/, "") + "/api/mlflow";
+  process.env.MLFLOW_TRACKING_TOKEN = apiKey;
+  process.env.MLFLOW_TRACKING_URI = trackingUri;
+  const experimentId = options.experimentId || process.env.MLFLOW_EXPERIMENT_ID || "0";
+  init({ trackingUri, experimentId });
+  _folder = resolveFolder(options.folder, options.experiment);
+  _configured = true;
+}
+function setFolder(folder) {
+  if (folder === null) {
+    _folder = null;
+  } else {
+    const sanitized = sanitizeFolder(folder);
+    _folder = sanitized || null;
+  }
+}
+function getFolder() {
+  return _folder;
+}
+function trace(fn, options = {}) {
+  const fnWithTag = (...args) => {
+    const result = fn(...args);
+    if (result instanceof Promise) {
+      return result.then((value) => {
+        injectFolderTag();
+        return value;
+      });
+    }
+    injectFolderTag();
+    return result;
+  };
+  const mlflowOptions = {};
+  if (options.name) mlflowOptions.name = options.name;
+  if (options.spanType) mlflowOptions.spanType = options.spanType;
+  if (options.attributes)
+    mlflowOptions.attributes = options.attributes;
+  return mlflowTrace(fnWithTag, mlflowOptions);
+}
+function startSpan(options) {
+  const mlflowOptions = {
+    name: options.name
+  };
+  if (options.spanType) mlflowOptions.spanType = options.spanType;
+  if (options.inputs) mlflowOptions.inputs = options.inputs;
+  const span = mlflowStartSpan(mlflowOptions);
+  const originalEnd = span.end.bind(span);
+  span.end = (endOptions) => {
+    injectFolderTag();
+    return originalEnd(endOptions);
+  };
+  return span;
+}
+function isConfigured() {
+  return _configured;
+}
+var kayba = {
+  configure,
+  trace,
+  startSpan,
+  setFolder,
+  getFolder,
+  isConfigured,
+  SpanType
+};
+var index_default = kayba;
+export {
+  SpanType2 as SpanType,
+  configure,
+  index_default as default,
+  getFolder,
+  isConfigured,
+  setFolder,
+  startSpan,
+  trace
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * Kayba tracing SDK for TypeScript/Node.js.\n *\n * Thin wrapper around `mlflow-tracing` that configures auth and\n * injects Kayba-specific folder tags.\n *\n * @example\n * ```ts\n * import kayba from \"@kayba_ai/tracing\";\n *\n * kayba.configure({\n *   apiKey: process.env.KAYBA_API_KEY,\n *   folder: \"my-project\",\n * });\n *\n * const myAgent = kayba.trace(async (topic: string) => {\n *   const span = kayba.startSpan({ name: \"retrieval\" });\n *   // ... work ...\n *   span.end({ status: \"OK\" });\n *   return result;\n * }, { name: \"research_agent\" });\n * ```\n */\n\nimport {\n  init,\n  trace as mlflowTrace,\n  startSpan as mlflowStartSpan,\n  updateCurrentTrace,\n  SpanType,\n  type TraceOptions as MlflowTraceOptions,\n  type SpanOptions as MlflowSpanOptions,\n} from \"mlflow-tracing\";\n\n// ── Constants ──────────────────────────────────────────────────────────\n\nconst DEFAULT_BASE_URL = \"https://use.kayba.ai\";\nconst MAX_FOLDER_LENGTH = 256;\nconst SAFE_FOLDER_RE = /[^a-zA-Z0-9 _\\-/.]/g;\nconst HTML_TAG_RE = /<[^>]*>/g;\n\n// ── Module state ───────────────────────────────────────────────────────\n\nlet _folder: string | null = null;\nlet _configured = false;\n\n// ── Types ──────────────────────────────────────────────────────────────\n\nexport interface ConfigureOptions {\n  /** Kayba API key. Falls back to `KAYBA_API_KEY` env var. */\n  apiKey?: string;\n  /** Kayba API base URL. Falls back to `KAYBA_API_URL` env var, then `https://use.kayba.ai`. */\n  baseUrl?: string;\n  /** Alias for `folder`. If both provided, `folder` takes precedence. */\n  experiment?: string;\n  /** Folder name for organizing traces in the Kayba dashboard. */\n  folder?: string;\n  /** MLflow experiment ID. Defaults to `\"0\"`. */\n  experimentId?: string;\n}\n\nexport interface TraceOptions {\n  /** Custom span name. Defaults to the function name. */\n  name?: string;\n  /** Span type (e.g. SpanType.LLM, SpanType.AGENT). */\n  spanType?: SpanType;\n  /** Additional span attributes. */\n  attributes?: Record<string, unknown>;\n}\n\nexport interface StartSpanOptions {\n  /** Span name. */\n  name: string;\n  /** Span type. */\n  spanType?: SpanType;\n  /** Input data to attach to the span. */\n  inputs?: Record<string, unknown>;\n}\n\n// ── Internal helpers ───────────────────────────────────────────────────\n\nfunction sanitizeFolder(name: string): string {\n  let clean = name.replace(HTML_TAG_RE, \"\");\n  clean = clean.replace(SAFE_FOLDER_RE, \"\");\n  return clean.trim().slice(0, MAX_FOLDER_LENGTH);\n}\n\nfunction resolveFolder(\n  folder: string | undefined,\n  experiment: string | undefined,\n): string | null {\n  const raw = folder ?? experiment;\n  if (!raw) return null;\n  const sanitized = sanitizeFolder(raw);\n  return sanitized || null;\n}\n\nfunction injectFolderTag(): void {\n  if (_folder !== null) {\n    try {\n      updateCurrentTrace({ tags: { \"kayba.folder\": _folder } });\n    } catch {\n      // Silently ignore if no active trace context.\n    }\n  }\n}\n\n// ── Public API ─────────────────────────────────────────────────────────\n\n/**\n * Configure Kayba tracing.\n *\n * Sets the MLflow tracking URI and authentication so that all\n * subsequent `trace` / `startSpan` calls export to Kayba.\n */\nexport function configure(options: ConfigureOptions = {}): void {\n  const apiKey = options.apiKey || process.env.KAYBA_API_KEY || \"\";\n\n  if (!apiKey) {\n    throw new Error(\n      \"No API key provided. Pass apiKey or set the KAYBA_API_KEY environment variable.\",\n    );\n  }\n\n  const baseUrl =\n    options.baseUrl || process.env.KAYBA_API_URL || DEFAULT_BASE_URL;\n\n  const trackingUri = baseUrl.replace(/\\/+$/, \"\") + \"/api/mlflow\";\n\n  // Configure MLflow under the hood.\n  process.env.MLFLOW_TRACKING_TOKEN = apiKey;\n  process.env.MLFLOW_TRACKING_URI = trackingUri;\n\n  const experimentId =\n    options.experimentId || process.env.MLFLOW_EXPERIMENT_ID || \"0\";\n\n  init({ trackingUri, experimentId });\n\n  _folder = resolveFolder(options.folder, options.experiment);\n  _configured = true;\n}\n\n/**\n * Change the target folder for subsequent traces.\n *\n * @param folder - Folder name, or `null` to clear (traces go to Unfiled).\n */\nexport function setFolder(folder: string | null): void {\n  if (folder === null) {\n    _folder = null;\n  } else {\n    const sanitized = sanitizeFolder(folder);\n    _folder = sanitized || null;\n  }\n}\n\n/** Return the currently configured folder, or `null`. */\nexport function getFolder(): string | null {\n  return _folder;\n}\n\n/**\n * Wrap a function with tracing. The returned function generates a span\n * each time it is called, with automatic folder tagging.\n *\n * @example\n * ```ts\n * const myFunc = trace(async (input: string) => {\n *   return doWork(input);\n * }, { name: \"my_func\", spanType: SpanType.LLM });\n * ```\n */\nexport function trace<T extends (...args: any[]) => any>(\n  fn: T,\n  options: TraceOptions = {},\n): T {\n  // Wrap the function to inject the folder tag after execution.\n  const fnWithTag = (...args: Parameters<T>): ReturnType<T> => {\n    const result = fn(...args);\n\n    // Handle async functions: inject tag after the promise resolves.\n    if (result instanceof Promise) {\n      return result.then((value: unknown) => {\n        injectFolderTag();\n        return value;\n      }) as ReturnType<T>;\n    }\n\n    injectFolderTag();\n    return result;\n  };\n\n  const mlflowOptions: MlflowTraceOptions = {};\n  if (options.name) mlflowOptions.name = options.name;\n  if (options.spanType) mlflowOptions.spanType = options.spanType;\n  if (options.attributes)\n    mlflowOptions.attributes = options.attributes as Record<string, any>;\n\n  return mlflowTrace(fnWithTag as T, mlflowOptions);\n}\n\n/**\n * Create a span manually. Call `.end()` when done.\n *\n * @example\n * ```ts\n * const span = startSpan({ name: \"retrieval\", spanType: SpanType.TOOL });\n * span.setInputs({ query });\n * // ... work ...\n * span.end({ outputs: { result }, status: \"OK\" });\n * ```\n */\nexport function startSpan(options: StartSpanOptions) {\n  const mlflowOptions: MlflowSpanOptions = {\n    name: options.name,\n  };\n  if (options.spanType) mlflowOptions.spanType = options.spanType;\n  if (options.inputs) mlflowOptions.inputs = options.inputs;\n\n  const span = mlflowStartSpan(mlflowOptions);\n\n  // Wrap .end() to inject the folder tag before closing.\n  const originalEnd = span.end.bind(span);\n  span.end = (endOptions?: Parameters<typeof span.end>[0]) => {\n    injectFolderTag();\n    return originalEnd(endOptions);\n  };\n\n  return span;\n}\n\n/** Returns whether `configure()` has been called. */\nexport function isConfigured(): boolean {\n  return _configured;\n}\n\n// ── Re-export MLflow types for convenience ─────────────────────────────\n\nexport { SpanType } from \"mlflow-tracing\";\nexport type { LiveSpan, Span } from \"mlflow-tracing\";\n\n// ── Default export ─────────────────────────────────────────────────────\n\nconst kayba = {\n  configure,\n  trace,\n  startSpan,\n  setFolder,\n  getFolder,\n  isConfigured,\n  SpanType,\n};\n\nexport default kayba;\n"],"mappings":";AAwBA;AAAA,EACE;AAAA,EACA,SAAS;AAAA,EACT,aAAa;AAAA,EACb;AAAA,EACA;AAAA,OAGK;AA8MP,SAAS,YAAAA,iBAAgB;AA1MzB,IAAM,mBAAmB;AACzB,IAAM,oBAAoB;AAC1B,IAAM,iBAAiB;AACvB,IAAM,cAAc;AAIpB,IAAI,UAAyB;AAC7B,IAAI,cAAc;AAqClB,SAAS,eAAe,MAAsB;AAC5C,MAAI,QAAQ,KAAK,QAAQ,aAAa,EAAE;AACxC,UAAQ,MAAM,QAAQ,gBAAgB,EAAE;AACxC,SAAO,MAAM,KAAK,EAAE,MAAM,GAAG,iBAAiB;AAChD;AAEA,SAAS,cACP,QACA,YACe;AACf,QAAM,MAAM,UAAU;AACtB,MAAI,CAAC,IAAK,QAAO;AACjB,QAAM,YAAY,eAAe,GAAG;AACpC,SAAO,aAAa;AACtB;AAEA,SAAS,kBAAwB;AAC/B,MAAI,YAAY,MAAM;AACpB,QAAI;AACF,yBAAmB,EAAE,MAAM,EAAE,gBAAgB,QAAQ,EAAE,CAAC;AAAA,IAC1D,QAAQ;AAAA,IAER;AAAA,EACF;AACF;AAUO,SAAS,UAAU,UAA4B,CAAC,GAAS;AAC9D,QAAM,SAAS,QAAQ,UAAU,QAAQ,IAAI,iBAAiB;AAE9D,MAAI,CAAC,QAAQ;AACX,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AAEA,QAAM,UACJ,QAAQ,WAAW,QAAQ,IAAI,iBAAiB;AAElD,QAAM,cAAc,QAAQ,QAAQ,QAAQ,EAAE,IAAI;AAGlD,UAAQ,IAAI,wBAAwB;AACpC,UAAQ,IAAI,sBAAsB;AAElC,QAAM,eACJ,QAAQ,gBAAgB,QAAQ,IAAI,wBAAwB;AAE9D,OAAK,EAAE,aAAa,aAAa,CAAC;AAElC,YAAU,cAAc,QAAQ,QAAQ,QAAQ,UAAU;AAC1D,gBAAc;AAChB;AAOO,SAAS,UAAU,QAA6B;AACrD,MAAI,WAAW,MAAM;AACnB,cAAU;AAAA,EACZ,OAAO;AACL,UAAM,YAAY,eAAe,MAAM;AACvC,cAAU,aAAa;AAAA,EACzB;AACF;AAGO,SAAS,YAA2B;AACzC,SAAO;AACT;AAaO,SAAS,MACd,IACA,UAAwB,CAAC,GACtB;AAEH,QAAM,YAAY,IAAI,SAAuC;AAC3D,UAAM,SAAS,GAAG,GAAG,IAAI;AAGzB,QAAI,kBAAkB,SAAS;AAC7B,aAAO,OAAO,KAAK,CAAC,UAAmB;AACrC,wBAAgB;AAChB,eAAO;AAAA,MACT,CAAC;AAAA,IACH;AAEA,oBAAgB;AAChB,WAAO;AAAA,EACT;AAEA,QAAM,gBAAoC,CAAC;AAC3C,MAAI,QAAQ,KAAM,eAAc,OAAO,QAAQ;AAC/C,MAAI,QAAQ,SAAU,eAAc,WAAW,QAAQ;AACvD,MAAI,QAAQ;AACV,kBAAc,aAAa,QAAQ;AAErC,SAAO,YAAY,WAAgB,aAAa;AAClD;AAaO,SAAS,UAAU,SAA2B;AACnD,QAAM,gBAAmC;AAAA,IACvC,MAAM,QAAQ;AAAA,EAChB;AACA,MAAI,QAAQ,SAAU,eAAc,WAAW,QAAQ;AACvD,MAAI,QAAQ,OAAQ,eAAc,SAAS,QAAQ;AAEnD,QAAM,OAAO,gBAAgB,aAAa;AAG1C,QAAM,cAAc,KAAK,IAAI,KAAK,IAAI;AACtC,OAAK,MAAM,CAAC,eAAgD;AAC1D,oBAAgB;AAChB,WAAO,YAAY,UAAU;AAAA,EAC/B;AAEA,SAAO;AACT;AAGO,SAAS,eAAwB;AACtC,SAAO;AACT;AASA,IAAM,QAAQ;AAAA,EACZ;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAEA,IAAO,gBAAQ;","names":["SpanType"]}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@kayba_ai/tracing",
+  "version": "0.1.0",
+  "description": "Kayba tracing SDK — instrument your AI agents and send traces to Kayba",
+  "license": "MIT",
+  "author": "Kayba.ai <hello@kayba.ai>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Kayba-ai/agentic-context-engine",
+    "directory": "sdk/typescript"
+  },
+  "homepage": "https://kayba.ai",
+  "keywords": [
+    "kayba",
+    "tracing",
+    "mlflow",
+    "observability",
+    "ai",
+    "agents"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "mlflow-tracing": "^0.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}