@mate-academy/llm-gateway 7.6.2 → 7.7.0

package/dist/utilities/llmTracing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utilities/llmTracing/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,wDAAsC;AACtC,qDAA6E;AAApE,qHAAA,kBAAkB,OAAA;AAAE,uHAAA,oBAAoB,OAAA;AACjD,iDAA+B;AAC/B,mDAAiC"}

package/dist/utilities/llmTracing/llmTracing.typedefs.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Trace/observation metadata. Values are coerced to strings before they reach
+ * the SDK, so callers may pass scalars.
+ */
+export type LLMTraceMetadata = Record<string, string | number | boolean>;
+export interface LLMTraceContext {
+    /** Overrides the trace name (defaults to the wrapping operation name). */
+    name?: string;
+    userId?: string;
+    sessionId?: string;
+    tags?: string[];
+    metadata?: LLMTraceMetadata;
+}
+/**
+ * Per-call generation capture passed from a provider service to the base
+ * service's success/error metric points. The observation name defaults to the
+ * service method when no prompt name is threaded through.
+ */
+export interface LLMGenerationTrace {
+    name: string;
+    input?: unknown;
+    output?: unknown;
+    modelParameters?: Record<string, unknown>;
+    metadata?: LLMTraceMetadata;
+}
+/**
+ * Full per-call generation record passed to `recordGeneration`. Extracted from
+ * `LLMGenerationTrace` so the gateway and `@mate-academy/llm-tracer` share the
+ * exact same recorded shape.
+ */
+export interface LLMGenerationTraceRecord extends LLMGenerationTrace {
+    model: string | null;
+    usageDetails?: Record<string, number>;
+    costDetails?: Record<string, number>;
+    isError?: boolean;
+}
+/**
+ * The tracing surface the gateway depends on. Any implementation (the no-op,
+ * or `@mate-academy/llm-tracer`'s Langfuse-backed tracer) satisfies it, so
+ * consumers hold a single type regardless of whether tracing is configured.
+ */
+export interface LLMGatewayTracer {
+    readonly isEnabled: boolean;
+    withTrace<Result>(name: string, context: LLMTraceContext, fn: () => Promise<Result>): Promise<Result>;
+    recordGeneration(generation: LLMGenerationTraceRecord): void;
+    withToolObservation<Result>(name: string, input: unknown, fn: () => Promise<Result>): Promise<Result>;
+    flush(): Promise<void>;
+}

package/dist/utilities/llmTracing/llmTracing.typedefs.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=llmTracing.typedefs.js.map

package/dist/utilities/llmTracing/llmTracing.typedefs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llmTracing.typedefs.js","sourceRoot":"","sources":["../../../src/utilities/llmTracing/llmTracing.typedefs.ts"],"names":[],"mappings":""}

package/dist/utilities/llmTracing/withLLMTrace.d.ts

@@ -0,0 +1,12 @@
+import { type LLMTraceMetadata } from '../../utilities/llmTracing/llmTracing.typedefs';
+/**
+ * Low-level trace wrapper for code outside the UseCase / Service base classes.
+ * Starts a trace named `name`; any gateway calls inside nest automatically via
+ * OTel context. A no-op when tracing is disabled.
+ */
+export declare function withLLMTrace<Result>(name: string, metadata: LLMTraceMetadata, fn: () => Promise<Result>): Promise<Result>;
+/**
+ * Flushes buffered traces. Serverless handlers call this on completion; the
+ * long-running API calls it from its shutdown hook only.
+ */
+export declare function flushLLMTraces(): Promise<void>;

package/dist/utilities/llmTracing/withLLMTrace.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withLLMTrace = withLLMTrace;
+exports.flushLLMTraces = flushLLMTraces;
+const activeLLMTracer_1 = require("../../utilities/llmTracing/activeLLMTracer");
+/**
+ * Low-level trace wrapper for code outside the UseCase / Service base classes.
+ * Starts a trace named `name`; any gateway calls inside nest automatically via
+ * OTel context. A no-op when tracing is disabled.
+ */
+function withLLMTrace(name, metadata, fn) {
+    return (0, activeLLMTracer_1.getActiveLLMTracer)().withTrace(name, { metadata }, fn);
+}
+/**
+ * Flushes buffered traces. Serverless handlers call this on completion; the
+ * long-running API calls it from its shutdown hook only.
+ */
+function flushLLMTraces() {
+    return (0, activeLLMTracer_1.getActiveLLMTracer)().flush();
+}
+//# sourceMappingURL=withLLMTrace.js.map

package/dist/utilities/llmTracing/withLLMTrace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"withLLMTrace.js","sourceRoot":"","sources":["../../../src/utilities/llmTracing/withLLMTrace.ts"],"names":[],"mappings":";;AAQA,oCAMC;AAMD,wCAEC;AAtBD,4EAA4E;AAG5E;;;;GAIG;AACH,SAAgB,YAAY,CAC1B,IAAY,EACZ,QAA0B,EAC1B,EAAyB;IAEzB,OAAO,IAAA,oCAAkB,GAAE,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC;AAChE,CAAC;AAED;;;GAGG;AACH,SAAgB,cAAc;IAC5B,OAAO,IAAA,oCAAkB,GAAE,CAAC,KAAK,EAAE,CAAC;AACtC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mate-academy/llm-gateway",
-  "version": "7.6.2",
+  "version": "7.7.0",
   "description": "A gateway package for LLM services.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -78,6 +78,7 @@
   },
   "dependencies": {
     "@google/genai": "^1.44.0",
+    "@langfuse/client": "^5.4.1",
     "axios": "^1.13.2",
     "load-esm": "^1.0.3",
     "mime-types": "^3.0.1",