@acarmisc/backstage-plugin-litellm-backend 0.22.0 → 0.24.0

package/config.d.ts

@@ -234,6 +234,45 @@ export interface Config {
       metadata?: { [key: string]: string };
     };
 
+    /**
+     * Langfuse answer-quality scores for the Insights tab ("Quality scores"
+     * card, GET /insights/quality). Generic Metrics API v2 integration: any
+     * Langfuse host works, and a disabled, unconfigured, or v3 server
+     * degrades to `{configured:false}` instead of erroring.
+     */
+    langfuse?: {
+      /**
+       * When true the /insights/quality route queries Langfuse.
+       * @default false
+       */
+      enabled?: boolean;
+
+      /**
+       * Langfuse host, e.g. https://langfuse.example.com.
+       * @visibility backend
+       */
+      baseUrl?: string;
+
+      /**
+       * Langfuse public key (Metrics API Basic-auth username).
+       * @visibility backend
+       */
+      publicKey?: string;
+
+      /**
+       * Langfuse secret key (Metrics API Basic-auth password).
+       * @visibility secret
+       */
+      secretKey?: string;
+
+      /**
+       * The Langfuse observation field holding the LiteLLM user id.
+       * Deployments whose agents tag traces differently change this one key.
+       * @default "userId"
+       */
+      userIdField?: string;
+    };
+
     /**
      * Caching configuration for backend data fetches.
      */

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { LiteLLMConfig, UserInfo, VirtualKey, ModelInfo, UsageMetrics, TeamInfo, GenerateKeyRequest, GenerateKeyResponse, UpdateKeyRequest, DeleteKeyRequest, CreateUserRequest, CreateUserResponse, CreateTeamRequest, CreateTeamResponse, UpdateTeamRequest, AuditLogsParams, PaginatedAuditLogs } from './types';
+import { LiteLLMConfig, UserInfo, VirtualKey, ModelInfo, UsageMetrics, TeamInfo, GenerateKeyRequest, GenerateKeyResponse, UpdateKeyRequest, DeleteKeyRequest, CreateUserRequest, CreateUserResponse, CreateTeamRequest, CreateTeamResponse, UpdateTeamRequest, AuditLogsParams, PaginatedAuditLogs, SpendLogsParams, PaginatedSpendLogs } from './types';
 /**
  * Typed error for failed upstream LiteLLM responses. Preserves the HTTP
  * status and the structured `param` (e.g. `key_alias`) from the upstream
@@ -185,4 +185,15 @@ export declare class LiteLLMClient {
     private transformDailyActivity;
     getUsage(startDate: string, endDate: string, userId: string): Promise<UsageMetrics>;
     getTeamUsage(teamId: string, startDate: string, endDate: string): Promise<UsageMetrics>;
+    /**
+     * Returns per-request spend rows from `/spend/logs` (retried as
+     * `/spend/logs/v2` on 404 — the path differs across LiteLLM versions).
+     * The response shape is version-dependent, so rows are parsed tolerantly:
+     * a bare array or a `{ data | results | logs }` envelope, with per-field
+     * fallbacks in normalizeSpendLogs.
+     */
+    getSpendLogs(params: SpendLogsParams & {
+        apiKeyHash?: string;
+    }): Promise<PaginatedSpendLogs>;
+    private normalizeSpendLogs;
 }

package/dist/client.js

@@ -683,5 +683,97 @@ class LiteLLMClient {
             throw err;
         }
     }
+    /**
+     * Returns per-request spend rows from `/spend/logs` (retried as
+     * `/spend/logs/v2` on 404 — the path differs across LiteLLM versions).
+     * The response shape is version-dependent, so rows are parsed tolerantly:
+     * a bare array or a `{ data | results | logs }` envelope, with per-field
+     * fallbacks in normalizeSpendLogs.
+     */
+    async getSpendLogs(params) {
+        const page = params.page ?? 1;
+        const pageSize = Math.min(params.pageSize ?? 25, 100);
+        const buildQuery = () => {
+            const q = new URLSearchParams({
+                summarize: 'false',
+                start_date: params.startDate,
+                end_date: params.endDate,
+                page: String(page),
+                page_size: String(pageSize),
+            });
+            if (params.userId)
+                q.set('user_id', params.userId);
+            if (params.teamId)
+                q.set('team_id', params.teamId);
+            if (params.apiKeyHash)
+                q.set('api_key', params.apiKeyHash);
+            return q.toString();
+        };
+        let raw;
+        try {
+            raw = await this.request(`/spend/logs?${buildQuery()}`);
+        }
+        catch (err) {
+            if (err instanceof LiteLLMUpstreamError && err.status === 404) {
+                raw = await this.request(`/spend/logs/v2?${buildQuery()}`);
+            }
+            else {
+                throw err;
+            }
+        }
+        return this.normalizeSpendLogs(raw, page, pageSize);
+    }
+    normalizeSpendLogs(raw, page, pageSize) {
+        const rows = [];
+        if (Array.isArray(raw))
+            rows.push(...raw);
+        else if (Array.isArray(raw?.data))
+            rows.push(...raw.data);
+        else if (Array.isArray(raw?.results))
+            rows.push(...raw.results);
+        else if (Array.isArray(raw?.logs))
+            rows.push(...raw.logs);
+        const toNum = (v, fallback = 0) => {
+            if (typeof v === 'number')
+                return Number.isFinite(v) ? v : fallback;
+            if (typeof v === 'string' && v.trim() !== '') {
+                const n = Number(v);
+                return Number.isFinite(n) ? n : fallback;
+            }
+            return fallback;
+        };
+        const data = rows.map((r) => {
+            const promptTokens = toNum(r?.prompt_tokens ?? r?.promptTokens ?? r?.input_tokens);
+            const completionTokens = toNum(r?.completion_tokens ?? r?.completionTokens ?? r?.output_tokens);
+            return {
+                requestId: String(r?.request_id ?? r?.requestId ?? r?.id ?? ''),
+                model: String(r?.model ?? r?.model_name ?? ''),
+                spend: toNum(r?.spend ?? r?.cost),
+                promptTokens,
+                completionTokens,
+                totalTokens: toNum(r?.total_tokens ?? r?.totalTokens, promptTokens + completionTokens),
+                status: String(r?.status ?? r?.request_status ?? 'unknown'),
+                cacheHit: Boolean(r?.cache_hit ?? r?.cacheHit ?? r?.cached === true),
+                ...(r?.user_id ?? r?.userId
+                    ? { userId: String(r.user_id ?? r.userId) }
+                    : {}),
+                ...(r?.team_id ?? r?.teamId
+                    ? { teamId: String(r.team_id ?? r.teamId) }
+                    : {}),
+                ...(r?.api_key ?? r?.keyHash
+                    ? { keyHash: String(r.api_key ?? r.keyHash) }
+                    : {}),
+                timestamp: String(r?.timestamp ?? r?.startTime ?? r?.created_at ?? r?.date ?? ''),
+            };
+        });
+        // Upstream truncation is not signalled in-band, so truncated = full page.
+        return {
+            data,
+            total: toNum(raw?.total ?? raw?.total_count, data.length),
+            page,
+            pageSize,
+            truncated: data.length >= pageSize,
+        };
+    }
 }
 exports.LiteLLMClient = LiteLLMClient;

package/dist/index.cjs.js

@@ -8022,7 +8022,7 @@ var import_backend_plugin_api = require("@backstage/backend-plugin-api");
 // src/router.ts
 var import_express = __toESM(require("express"));
 var import_plugin_permission_common2 = __toESM(require_index_cjs2());
-var import_errors21 = __toESM(require_index_cjs());
+var import_errors22 = __toESM(require_index_cjs());
 var import_catalog_client = require("@backstage/catalog-client");
 
 // src/client.ts
@@ -8655,6 +8655,90 @@ var LiteLLMClient = class {
       throw err;
     }
   }
+  /**
+   * Returns per-request spend rows from `/spend/logs` (retried as
+   * `/spend/logs/v2` on 404 — the path differs across LiteLLM versions).
+   * The response shape is version-dependent, so rows are parsed tolerantly:
+   * a bare array or a `{ data | results | logs }` envelope, with per-field
+   * fallbacks in normalizeSpendLogs.
+   */
+  async getSpendLogs(params) {
+    const page = params.page ?? 1;
+    const pageSize = Math.min(params.pageSize ?? 25, 100);
+    const buildQuery = () => {
+      const q = new URLSearchParams({
+        summarize: "false",
+        start_date: params.startDate,
+        end_date: params.endDate,
+        page: String(page),
+        page_size: String(pageSize)
+      });
+      if (params.userId) q.set("user_id", params.userId);
+      if (params.teamId) q.set("team_id", params.teamId);
+      if (params.apiKeyHash) q.set("api_key", params.apiKeyHash);
+      return q.toString();
+    };
+    let raw;
+    try {
+      raw = await this.request(`/spend/logs?${buildQuery()}`);
+    } catch (err) {
+      if (err instanceof LiteLLMUpstreamError && err.status === 404) {
+        raw = await this.request(`/spend/logs/v2?${buildQuery()}`);
+      } else {
+        throw err;
+      }
+    }
+    return this.normalizeSpendLogs(raw, page, pageSize);
+  }
+  normalizeSpendLogs(raw, page, pageSize) {
+    const rows = [];
+    if (Array.isArray(raw)) rows.push(...raw);
+    else if (Array.isArray(raw?.data)) rows.push(...raw.data);
+    else if (Array.isArray(raw?.results)) rows.push(...raw.results);
+    else if (Array.isArray(raw?.logs)) rows.push(...raw.logs);
+    const toNum2 = (v, fallback = 0) => {
+      if (typeof v === "number") return Number.isFinite(v) ? v : fallback;
+      if (typeof v === "string" && v.trim() !== "") {
+        const n = Number(v);
+        return Number.isFinite(n) ? n : fallback;
+      }
+      return fallback;
+    };
+    const data = rows.map((r) => {
+      const promptTokens = toNum2(
+        r?.prompt_tokens ?? r?.promptTokens ?? r?.input_tokens
+      );
+      const completionTokens = toNum2(
+        r?.completion_tokens ?? r?.completionTokens ?? r?.output_tokens
+      );
+      return {
+        requestId: String(r?.request_id ?? r?.requestId ?? r?.id ?? ""),
+        model: String(r?.model ?? r?.model_name ?? ""),
+        spend: toNum2(r?.spend ?? r?.cost),
+        promptTokens,
+        completionTokens,
+        totalTokens: toNum2(
+          r?.total_tokens ?? r?.totalTokens,
+          promptTokens + completionTokens
+        ),
+        status: String(r?.status ?? r?.request_status ?? "unknown"),
+        cacheHit: Boolean(r?.cache_hit ?? r?.cacheHit ?? r?.cached === true),
+        ...r?.user_id ?? r?.userId ? { userId: String(r.user_id ?? r.userId) } : {},
+        ...r?.team_id ?? r?.teamId ? { teamId: String(r.team_id ?? r.teamId) } : {},
+        ...r?.api_key ?? r?.keyHash ? { keyHash: String(r.api_key ?? r.keyHash) } : {},
+        timestamp: String(
+          r?.timestamp ?? r?.startTime ?? r?.created_at ?? r?.date ?? ""
+        )
+      };
+    });
+    return {
+      data,
+      total: toNum2(raw?.total ?? raw?.total_count, data.length),
+      page,
+      pageSize,
+      truncated: data.length >= pageSize
+    };
+  }
 };
 
 // src/errors.ts
@@ -9446,6 +9530,21 @@ function redactTeamMemberUsage(usage) {
   };
 }
 
+// src/langfuse.ts
+function readLangfuseConfig(config) {
+  const enabled = config.getOptionalBoolean("litellm.langfuse.enabled") ?? false;
+  return {
+    enabled,
+    baseUrl: config.getOptionalString("litellm.langfuse.baseUrl") ?? null,
+    publicKey: config.getOptionalString("litellm.langfuse.publicKey") ?? null,
+    secretKey: config.getOptionalString("litellm.langfuse.secretKey") ?? null,
+    userIdField: config.getOptionalString("litellm.langfuse.userIdField") ?? "userId"
+  };
+}
+function isLangfuseConfigured(cfg) {
+  return cfg.enabled && !!cfg.baseUrl && !!cfg.publicKey && !!cfg.secretKey;
+}
+
 // src/routes/middleware/withUser.ts
 function createRequireUser(ctx) {
   return async (req, res, next) => {
@@ -11482,6 +11581,218 @@ function registerTeamUsageRoutes(router, ctx) {
   }
 }
 
+// src/langfuseClient.ts
+var DEFAULT_TIMEOUT2 = 15e3;
+var LangfuseUpstreamError = class extends Error {
+  constructor(status, statusText) {
+    super(`Langfuse API error: ${status} ${statusText}`);
+    this.status = status;
+  }
+};
+async function queryMetrics(baseUrl, publicKey, secretKey, queryObj, timeout = DEFAULT_TIMEOUT2) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+  try {
+    const url = `${baseUrl.replace(/\/$/, "")}/api/public/v2/metrics?query=${encodeURIComponent(
+      JSON.stringify(queryObj)
+    )}`;
+    const response = await fetch(url, {
+      signal: controller.signal,
+      headers: {
+        Authorization: `Basic ${Buffer.from(`${publicKey}:${secretKey}`).toString("base64")}`
+      }
+    });
+    if (!response.ok) {
+      throw new LangfuseUpstreamError(response.status, response.statusText);
+    }
+    return response.json();
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+function toNum(v) {
+  if (typeof v === "number") return Number.isFinite(v) ? v : null;
+  if (typeof v === "string" && v.trim() !== "") {
+    const n = Number(v);
+    return Number.isFinite(n) ? n : null;
+  }
+  return null;
+}
+function pick(row, names) {
+  const scopes = [row, row?.metrics, row?.dimensions];
+  for (const scope of scopes) {
+    if (!scope || typeof scope !== "object") continue;
+    for (const name of names) {
+      const n = toNum(scope[name]);
+      if (n !== null) return n;
+    }
+  }
+  return null;
+}
+function pickText(row, names) {
+  const scopes = [row, row?.metrics, row?.dimensions];
+  for (const scope of scopes) {
+    if (!scope || typeof scope !== "object") continue;
+    for (const name of names) {
+      const v = scope[name];
+      if (typeof v === "string" && v) return v;
+    }
+  }
+  return null;
+}
+function metricRows(body) {
+  if (Array.isArray(body)) return body;
+  if (Array.isArray(body?.data)) return body.data;
+  if (Array.isArray(body?.results)) return body.results;
+  if (Array.isArray(body?.rows)) return body.rows;
+  return [];
+}
+function parseObservations(body) {
+  const byModel = metricRows(body).map((row) => ({
+    model: pickText(row, ["providedModelName", "model", "modelName"]) ?? "",
+    cost: pick(row, ["sum_totalCost", "totalCost", "sum_total_cost", "cost", "sum_cost"]) ?? 0,
+    tokens: pick(row, ["sum_totalTokens", "totalTokens", "sum_total_tokens", "tokens"]) ?? 0,
+    avgLatencyMs: pick(row, ["avg_latency", "latency", "avg_latency_ms", "latencyMs"]),
+    requests: pick(row, ["count_id", "count", "id_count", "requests", "observations"]) ?? 0
+  })).filter((r) => r.model !== "");
+  byModel.sort((a, b) => b.cost - a.cost);
+  return byModel;
+}
+function parseScores(body) {
+  const scores = metricRows(body).map((row) => ({
+    name: pickText(row, ["name", "scoreName"]) ?? "",
+    avg: pick(row, ["avg_value", "value", "avg"]) ?? NaN,
+    count: pick(row, ["count_id", "count", "id_count", "scores"]) ?? 0
+  })).filter((s) => s.name !== "" && Number.isFinite(s.avg));
+  scores.sort((a, b) => a.name.localeCompare(b.name));
+  return scores;
+}
+function toTimestamp(day2, endOfDay) {
+  if (/^\d{4}-\d{2}-\d{2}$/.test(day2)) {
+    return endOfDay ? `${day2}T23:59:59.999Z` : `${day2}T00:00:00.000Z`;
+  }
+  return day2;
+}
+async function getQualitySummary(cfg, opts) {
+  if (!isLangfuseConfigured(cfg)) return null;
+  const { baseUrl, publicKey, secretKey, userIdField } = cfg;
+  const fromTimestamp = toTimestamp(opts.from, false);
+  const toTimestampValue = toTimestamp(opts.to, true);
+  try {
+    const observations = await queryMetrics(baseUrl, publicKey, secretKey, {
+      view: "observations",
+      metrics: [
+        { measure: "totalCost", aggregation: "SUM" },
+        { measure: "totalTokens", aggregation: "SUM" },
+        { measure: "latency", aggregation: "AVG" },
+        { measure: "id", aggregation: "COUNT" }
+      ],
+      dimensions: [{ field: "providedModelName" }],
+      filters: [
+        { column: userIdField, operator: "=", value: opts.userId, type: "string" }
+      ],
+      fromTimestamp,
+      toTimestamp: toTimestampValue,
+      config: { row_limit: 50 }
+    });
+    let scores = [];
+    try {
+      const scoresBody = await queryMetrics(baseUrl, publicKey, secretKey, {
+        view: "scores-numeric",
+        metrics: [
+          { measure: "value", aggregation: "AVG" },
+          { measure: "id", aggregation: "COUNT" }
+        ],
+        dimensions: [{ field: "name" }],
+        fromTimestamp,
+        toTimestamp: toTimestampValue,
+        config: { row_limit: 50 }
+      });
+      scores = parseScores(scoresBody);
+    } catch {
+      scores = [];
+    }
+    return { configured: true, byModel: parseObservations(observations), scores };
+  } catch {
+    return null;
+  }
+}
+
+// src/routes/insights.ts
+function registerInsightsRoutes(router, ctx) {
+  const { client, catalogClient, auth, logger, auditGroup } = ctx;
+  const requireUser = createRequireUser(ctx);
+  router.get("/insights/spend-logs", requireUser, async (req, res) => {
+    try {
+      const { start_date, end_date, userId, teamId, page, page_size } = req.query;
+      if (!start_date || !end_date) {
+        res.status(400).json({ error: "start_date and end_date are required" });
+        return;
+      }
+      const tokenEntityRef = res.locals.tokenEntityRef;
+      await getProvisionedUser(ctx, res);
+      const callerId = res.locals.userId;
+      const isAudit = auditGroup ? await isUserMemberOfGroup(
+        tokenEntityRef,
+        auditGroup,
+        catalogClient,
+        auth,
+        logger
+      ) : false;
+      const result = await client.getSpendLogs({
+        startDate: start_date,
+        endDate: end_date,
+        userId: isAudit ? userId || callerId : callerId,
+        teamId: isAudit ? teamId : void 0,
+        page: page ? Number(page) : void 0,
+        pageSize: page_size ? Number(page_size) : void 0
+      });
+      res.json(result);
+    } catch (error) {
+      if (error instanceof ProvisioningError) {
+        res.status(error.status).json(error.body);
+        return;
+      }
+      sendError(res, error, logger, "fetch spend logs");
+    }
+  });
+  router.get("/insights/quality", requireUser, async (req, res) => {
+    try {
+      const { start_date, end_date, userId } = req.query;
+      if (!start_date || !end_date) {
+        res.status(400).json({ error: "start_date and end_date are required" });
+        return;
+      }
+      const tokenEntityRef = res.locals.tokenEntityRef;
+      await getProvisionedUser(ctx, res);
+      const callerId = res.locals.userId;
+      const isAudit = auditGroup ? await isUserMemberOfGroup(
+        tokenEntityRef,
+        auditGroup,
+        catalogClient,
+        auth,
+        logger
+      ) : false;
+      if (!isLangfuseConfigured(ctx.langfuseCfg)) {
+        res.json({ configured: false });
+        return;
+      }
+      const summary = await getQualitySummary(ctx.langfuseCfg, {
+        from: start_date,
+        to: end_date,
+        userId: isAudit ? userId || callerId : callerId
+      });
+      res.json(summary ?? { configured: false });
+    } catch (error) {
+      if (error instanceof ProvisioningError) {
+        res.status(error.status).json(error.body);
+        return;
+      }
+      sendError(res, error, logger, "fetch quality summary");
+    }
+  });
+}
+
 // node_modules/jose/dist/node/esm/runtime/base64url.js
 var import_node_buffer = require("node:buffer");
 
@@ -13220,6 +13531,7 @@ async function createRouter(options) {
   const teamBudgetVisibility = readTeamBudgetVisibility(config);
   const opencodeCfg = readOpencodeConfig(config);
   const memberBreakdownCfg = readMemberBreakdownConfig(config);
+  const langfuseCfg = readLangfuseConfig(config);
   const catalogClient = options.catalogClient ?? new import_catalog_client.CatalogClient({ discoveryApi: discovery });
   if (provisioningEnabled) {
     logger.info(
@@ -13266,17 +13578,18 @@ async function createRouter(options) {
     teamBudgetVisibility,
     opencodeCfg,
     memberBreakdownCfg,
+    langfuseCfg,
     // Helper functions - defined inline below this object
     authorizeKeyAction: async (req, keyId) => {
       if (!req.res || !req.res.locals.tokenEntityRef || !req.res.locals.userId) {
-        throw new import_errors21.NotAllowedError("User identity not found in request");
+        throw new import_errors22.NotAllowedError("User identity not found in request");
       }
       const tokenEntityRef = req.res.locals.tokenEntityRef;
       const userId = await resolveMemberUserId(tokenEntityRef);
       const ownKeys = await client.listKeys(userId);
       const key = ownKeys.find((k) => (k.token ?? k.key) === keyId);
       if (!key) {
-        throw new import_errors21.NotAllowedError("Access denied: key does not belong to the caller");
+        throw new import_errors22.NotAllowedError("Access denied: key does not belong to the caller");
       }
       return { tokenEntityRef, userId, key };
     },
@@ -13410,13 +13723,14 @@ async function createRouter(options) {
   router.use(import_express.default.json());
   router.use(import_express.default.urlencoded({ extended: false }));
   const requireUser = createRequireUser(ctx);
-  router.use(["/user/info", "/keys", "/usage"], requireUser);
+  router.use(["/user/info", "/keys", "/usage", "/insights"], requireUser);
   registerConfigRoutes(router, ctx);
   registerKeysRoutes(router, ctx);
   registerOpencodeRoutes(router, ctx);
   registerTeamsRoutes(router, ctx);
   registerObjectPermissionsRoutes(router, ctx);
   registerTeamUsageRoutes(router, ctx);
+  registerInsightsRoutes(router, ctx);
   registerBridgeRoutes(router, ctx, { config, tokenVerifier: options.tokenVerifier });
   return router;
 }