convex-langfuse 0.0.1

package/src/component/lib.ts

@@ -0,0 +1,252 @@
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server.js";
+
+const observationTypeValidator = v.union(
+  v.literal("span"),
+  v.literal("generation"),
+  v.literal("event"),
+  v.literal("embedding"),
+  v.literal("agent"),
+  v.literal("tool"),
+  v.literal("chain"),
+  v.literal("retriever"),
+  v.literal("guardrail"),
+  v.literal("evaluator"),
+);
+
+const levelValidator = v.union(
+  v.literal("DEBUG"),
+  v.literal("DEFAULT"),
+  v.literal("WARNING"),
+  v.literal("ERROR"),
+);
+
+const traceValidator = v.object({
+  _id: v.id("traces"),
+  _creationTime: v.number(),
+  traceId: v.string(),
+  name: v.string(),
+  userId: v.optional(v.string()),
+  sessionId: v.optional(v.string()),
+  tags: v.optional(v.array(v.string())),
+  metadata: v.optional(v.string()),
+  release: v.optional(v.string()),
+  createdAt: v.number(),
+  updatedAt: v.number(),
+});
+
+const observationValidator = v.object({
+  _id: v.id("observations"),
+  _creationTime: v.number(),
+  observationId: v.string(),
+  traceId: v.string(),
+  type: observationTypeValidator,
+  name: v.string(),
+  input: v.optional(v.string()),
+  output: v.optional(v.string()),
+  model: v.optional(v.string()),
+  inputTokens: v.optional(v.number()),
+  outputTokens: v.optional(v.number()),
+  level: levelValidator,
+  statusMessage: v.optional(v.string()),
+  metadata: v.optional(v.string()),
+  startedAt: v.number(),
+  endedAt: v.number(),
+  createdAt: v.number(),
+});
+
+const scoreValidator = v.object({
+  _id: v.id("scores"),
+  _creationTime: v.number(),
+  scoreId: v.string(),
+  traceId: v.string(),
+  name: v.string(),
+  value: v.number(),
+  comment: v.optional(v.string()),
+  createdAt: v.number(),
+});
+
+// ─── Queries ────────────────────────────────────────────────────────────────
+
+export const getTrace = query({
+  args: { traceId: v.string() },
+  returns: v.union(v.null(), traceValidator),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("traces")
+      .withIndex("by_traceId", (q) => q.eq("traceId", args.traceId))
+      .first();
+  },
+});
+
+export const listTracesByUser = query({
+  args: { userId: v.string(), limit: v.optional(v.number()) },
+  returns: v.array(traceValidator),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("traces")
+      .withIndex("by_userId", (q) => q.eq("userId", args.userId))
+      .order("desc")
+      .take(args.limit ?? 50);
+  },
+});
+
+export const listTracesBySession = query({
+  args: { sessionId: v.string(), limit: v.optional(v.number()) },
+  returns: v.array(traceValidator),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("traces")
+      .withIndex("by_sessionId", (q) => q.eq("sessionId", args.sessionId))
+      .order("desc")
+      .take(args.limit ?? 50);
+  },
+});
+
+export const listObservations = query({
+  args: { traceId: v.string() },
+  returns: v.array(observationValidator),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("observations")
+      .withIndex("by_traceId", (q) => q.eq("traceId", args.traceId))
+      .order("asc")
+      .collect();
+  },
+});
+
+export const listScores = query({
+  args: { traceId: v.string() },
+  returns: v.array(scoreValidator),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("scores")
+      .withIndex("by_traceId", (q) => q.eq("traceId", args.traceId))
+      .collect();
+  },
+});
+
+// Every trace, newest first, regardless of which user/session it belongs to.
+// Unlike listTracesByUser/listTracesBySession, this doesn't require already
+// knowing an identity to look under — useful for a "history" view where the
+// caller's own userId/sessionId is only a client-side value that doesn't
+// survive a page reload.
+export const listRecentTraces = query({
+  args: { limit: v.optional(v.number()) },
+  returns: v.array(traceValidator),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("traces")
+      .order("desc")
+      .take(args.limit ?? 50);
+  },
+});
+
+export const getStats = query({
+  args: {},
+  returns: v.object({ traces: v.number(), observations: v.number(), scores: v.number() }),
+  handler: async (ctx) => {
+    const [traces, observations, scores] = await Promise.all([
+      ctx.db.query("traces").collect(),
+      ctx.db.query("observations").collect(),
+      ctx.db.query("scores").collect(),
+    ]);
+    return { traces: traces.length, observations: observations.length, scores: scores.length };
+  },
+});
+
+// ─── Mutations ──────────────────────────────────────────────────────────────
+
+export const recordTrace = mutation({
+  args: {
+    traceId: v.string(),
+    name: v.string(),
+    userId: v.optional(v.string()),
+    sessionId: v.optional(v.string()),
+    tags: v.optional(v.array(v.string())),
+    metadata: v.optional(v.string()),
+    release: v.optional(v.string()),
+  },
+  returns: v.id("traces"),
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const existing = await ctx.db
+      .query("traces")
+      .withIndex("by_traceId", (q) => q.eq("traceId", args.traceId))
+      .first();
+
+    if (existing) {
+      await ctx.db.patch(existing._id, { ...args, updatedAt: now });
+      return existing._id;
+    }
+
+    return await ctx.db.insert("traces", {
+      ...args,
+      createdAt: now,
+      updatedAt: now,
+    });
+  },
+});
+
+export const recordObservation = mutation({
+  args: {
+    observationId: v.string(),
+    traceId: v.string(),
+    type: observationTypeValidator,
+    name: v.string(),
+    input: v.optional(v.string()),
+    output: v.optional(v.string()),
+    model: v.optional(v.string()),
+    inputTokens: v.optional(v.number()),
+    outputTokens: v.optional(v.number()),
+    level: levelValidator,
+    statusMessage: v.optional(v.string()),
+    metadata: v.optional(v.string()),
+    startedAt: v.number(),
+    endedAt: v.number(),
+  },
+  returns: v.id("observations"),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("observations")
+      .withIndex("by_observationId", (q) => q.eq("observationId", args.observationId))
+      .first();
+
+    if (existing) {
+      await ctx.db.patch(existing._id, args);
+      return existing._id;
+    }
+
+    return await ctx.db.insert("observations", {
+      ...args,
+      createdAt: Date.now(),
+    });
+  },
+});
+
+export const recordScore = mutation({
+  args: {
+    scoreId: v.string(),
+    traceId: v.string(),
+    name: v.string(),
+    value: v.number(),
+    comment: v.optional(v.string()),
+  },
+  returns: v.id("scores"),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("scores")
+      .withIndex("by_scoreId", (q) => q.eq("scoreId", args.scoreId))
+      .first();
+
+    if (existing) {
+      await ctx.db.patch(existing._id, args);
+      return existing._id;
+    }
+
+    return await ctx.db.insert("scores", {
+      ...args,
+      createdAt: Date.now(),
+    });
+  },
+});

package/src/component/schema.ts

@@ -0,0 +1,66 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  traces: defineTable({
+    traceId: v.string(),
+    name: v.string(),
+    userId: v.optional(v.string()),
+    sessionId: v.optional(v.string()),
+    tags: v.optional(v.array(v.string())),
+    metadata: v.optional(v.string()),
+    release: v.optional(v.string()),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  })
+    .index("by_traceId", ["traceId"])
+    .index("by_userId", ["userId"])
+    .index("by_sessionId", ["sessionId"]),
+
+  observations: defineTable({
+    observationId: v.string(),
+    traceId: v.string(),
+    type: v.union(
+      v.literal("span"),
+      v.literal("generation"),
+      v.literal("event"),
+      v.literal("embedding"),
+      v.literal("agent"),
+      v.literal("tool"),
+      v.literal("chain"),
+      v.literal("retriever"),
+      v.literal("guardrail"),
+      v.literal("evaluator"),
+    ),
+    name: v.string(),
+    input: v.optional(v.string()),
+    output: v.optional(v.string()),
+    model: v.optional(v.string()),
+    inputTokens: v.optional(v.number()),
+    outputTokens: v.optional(v.number()),
+    level: v.union(
+      v.literal("DEBUG"),
+      v.literal("DEFAULT"),
+      v.literal("WARNING"),
+      v.literal("ERROR"),
+    ),
+    statusMessage: v.optional(v.string()),
+    metadata: v.optional(v.string()),
+    startedAt: v.number(),
+    endedAt: v.number(),
+    createdAt: v.number(),
+  })
+    .index("by_observationId", ["observationId"])
+    .index("by_traceId", ["traceId"]),
+
+  scores: defineTable({
+    scoreId: v.string(),
+    traceId: v.string(),
+    name: v.string(),
+    value: v.number(),
+    comment: v.optional(v.string()),
+    createdAt: v.number(),
+  })
+    .index("by_scoreId", ["scoreId"])
+    .index("by_traceId", ["traceId"]),
+});

package/src/component/setup.test.ts

@@ -0,0 +1,11 @@
+/// <reference types="vite/client" />
+import { test } from "vitest";
+import schema from "./schema.js";
+import { convexTest } from "convex-test";
+export const modules = import.meta.glob("./**/*.*s");
+
+export function initConvexTest() {
+  const t = convexTest(schema, modules);
+  return t;
+}
+test("setup", () => {});

package/src/test.ts

@@ -0,0 +1,18 @@
+/// <reference types="vite/client" />
+import type { TestConvex } from "convex-test";
+import type { GenericSchema, SchemaDefinition } from "convex/server";
+import schema from "./component/schema.js";
+const modules = import.meta.glob("./component/**/*.ts");
+
+/**
+ * Register the component with the test convex instance.
+ * @param t - The test convex instance, e.g. from calling `convexTest`.
+ * @param name - The name of the component, as registered in convex.config.ts.
+ */
+export function register(
+  t: TestConvex<SchemaDefinition<GenericSchema, boolean>>,
+  name: string = "convexLangfuse",
+) {
+  t.registerComponent(name, schema, modules);
+}
+export default { register, schema, modules };