@langinsight/ai-sdk 0.0.1 → 0.0.2

package/README.md

@@ -1,6 +1,6 @@
 # @langinsight/ai-sdk
 
-LangInsight callback handler for Vercel AI SDK.
+LangInsight callback handler for Vercel AI SDK. Sends input/output traces to LangInsight in parallel and supports feedback (thumbs up/down) via `score()`.
 
 ## Usage
 
@@ -26,8 +26,8 @@ const result = await generateText({
   prompt,
 });
 
-// Report the result to LangInsight
-await handler.report(result, { input: prompt });
+// Report the result to LangInsight (returns output trace id or undefined)
+const traceId = await handler.report(result, { input: prompt });
 ```
 
 ### streamText
@@ -43,6 +43,8 @@ const handler = new LangInsight.CallbackHandler({
   apiKey: LANGINSIGHT_API_KEY,
   endpoint: LANGINSIGHT_ENDPOINT,
   metadata: { userId: "admin", sessionId: "admin" },
+  onSuccess: (trace) => console.log("Trace sent:", trace.id),
+  onFailure: (err) => console.error("Trace failed:", err),
 });
 
 const prompt = "Hello!";
@@ -50,7 +52,6 @@ const prompt = "Hello!";
 const result = streamText({
   model: openai("gpt-4o"),
   prompt,
-  // Specify callback handler as onFinish
   onFinish: handler.onFinish({ input: prompt }),
 });
 
@@ -59,11 +60,36 @@ for await (const chunk of result.textStream) {
 }
 ```
 
+### Feedback (score)
+
+After sending traces, you can submit feedback for the last output trace using `score()` or the trace id from `onSuccess` / `report()`.
+
+```typescript
+// Using lastTraceId (set after report() or onFinish)
+await handler.score({ traceId: handler.lastTraceId, value: 1 }); // 👍
+await handler.score({ traceId: handler.lastTraceId, value: -1 }); // 👎
+
+// Or using the trace id from report() / onSuccess
+await handler.score({ traceId, value: 1 });
+```
+
 ## Options
 
-- `apiKey`: LangInsight API key (required)
-- `endpoint`: LangInsight API endpoint (required)
-- `metadata`: Metadata to attach to trace information (required)
-  - `userId`: User ID
-  - `sessionId`: Session ID
-  - Any other key-value pairs
+| Option      | Type                              | Required | Description                                                                 |
+| ----------- | --------------------------------- | -------- | --------------------------------------------------------------------------- |
+| `apiKey`    | `string`                          | Yes      | LangInsight API key                                                         |
+| `endpoint`  | `string`                          | Yes      | LangInsight API endpoint (e.g. `https://api.langinsight.example.com`)       |
+| `metadata`  | `object`                          | Yes      | Metadata attached to traces                                                 |
+| `metadata.userId`    | `string` | Yes      | User ID                                                                     |
+| `metadata.sessionId`| `string` | Yes      | Session ID (e.g. conversation id)                                          |
+| `metadata.modelName` | `string` | No       | Model name (defaults to result response when not set)                       |
+| `metadata.*`         | `any`   | No       | Additional key-value pairs                                                  |
+| `onSuccess` | `(trace: Trace) => void`         | No       | Callback invoked with the output trace when trace submission succeeds       |
+| `onFailure` | `(error: Error) => void`         | No       | Callback invoked with the error when trace submission fails                 |
+
+## API
+
+- **`report(result, { input })`** — Sends traces for a `generateText` result. Returns the output trace id, or `undefined` on failure.
+- **`onFinish({ input })`** — Returns a function suitable for `streamText`’s `onFinish`. Sends traces when the stream finishes.
+- **`score({ traceId, value })`** — Submits feedback (1 = thumbs up, -1 = thumbs down) for the given trace.
+- **`lastTraceId`** — The id of the last output trace sent by this handler (set after `report()` or `onFinish()`).

package/dist/index.cjs

@@ -323,6 +323,8 @@ var LangInsight;
       this.client = hc(options.endpoint, { fetch });
     }
     client;
+    /** 最後に送信した output trace の ID */
+    lastTraceId;
     /**
      * streamText の onFinish コールバックとして使用
      *
@@ -348,6 +350,8 @@ var LangInsight;
     /**
      * generateText の結果を送信
      *
+     * @returns output trace の traceId（送信失敗時は undefined）
+     *
      * @example
      * ```ts
      * const handler = new LangInsight.CallbackHandler(options);
@@ -357,61 +361,96 @@ var LangInsight;
      *   prompt: "Hello!",
      * });
      *
-     * await handler.report(result, { input: "Hello!" });
+     * const traceId = await handler.report(result, { input: "Hello!" });
      * ```
      */
     // biome-ignore lint/suspicious/noExplicitAny: should accept any output
     async report(result, params) {
-      await this.sendTraces({
+      return await this.sendTraces({
         input: params.input,
         result
       });
     }
-    async sendTraces(params) {
-      const { input, result } = params;
-      const { userId, sessionId, ...rest } = this.options.metadata;
-      const model = result.response.modelId ?? "unknown";
-      const startedAt = result.response.timestamp;
-      const endedAt = /* @__PURE__ */ new Date();
-      const inputRes = await this.client.traces.external.$post({
+    /**
+     * フィードバック（👍/👎）を送信
+     *
+     * @example
+     * ```ts
+     * await handler.score({ traceId, value: 1 }); // 👍
+     * await handler.score({ traceId, value: -1 }); // 👎
+     * ```
+     */
+    async score(params) {
+      const { userId, sessionId } = this.options.metadata;
+      const res = await this.client.feedbacks.external.$post({
         header: {
           "x-api-key": this.options.apiKey
         },
         json: {
-          userId,
+          traceId: params.traceId,
           sessionId,
-          model,
-          token: result.usage.inputTokens ?? 0,
-          content: input,
-          type: "input",
-          meta: { ...rest },
-          startedAt: startedAt.toISOString(),
-          endedAt: endedAt.toISOString()
+          userId,
+          value: params.value
         }
       });
-      if (!inputRes.ok) {
-        console.error(await inputRes.text());
-        return;
+      if (!res.ok) {
+        console.error(await res.text());
       }
-      const outputRes = await this.client.traces.external.$post({
-        header: {
-          "x-api-key": this.options.apiKey
-        },
-        json: {
-          userId,
-          sessionId,
-          model,
-          token: result.usage.outputTokens ?? 0,
-          content: result.text,
-          type: "output",
-          meta: { ...rest },
-          startedAt: startedAt.toISOString(),
-          endedAt: endedAt.toISOString()
+    }
+    async sendTraces(params) {
+      const { input, result } = params;
+      const { userId, sessionId, ...rest } = this.options.metadata;
+      const model = result.response.modelId ?? "unknown";
+      const startedAt = result.response.timestamp;
+      const endedAt = /* @__PURE__ */ new Date();
+      try {
+        const res = await Promise.all([
+          this.client.traces.external.$post({
+            header: {
+              "x-api-key": this.options.apiKey
+            },
+            json: {
+              userId,
+              sessionId,
+              model,
+              token: result.usage.inputTokens ?? 0,
+              content: input,
+              type: "input",
+              meta: { ...rest },
+              startedAt: startedAt.toISOString(),
+              endedAt: endedAt.toISOString()
+            }
+          }),
+          this.client.traces.external.$post({
+            header: {
+              "x-api-key": this.options.apiKey
+            },
+            json: {
+              userId,
+              sessionId,
+              model,
+              token: result.usage.outputTokens ?? 0,
+              content: result.text,
+              type: "output",
+              meta: { ...rest },
+              startedAt: startedAt.toISOString(),
+              endedAt: endedAt.toISOString()
+            }
+          })
+        ]);
+        if (!res.every((r) => r.ok)) {
+          console.error(await Promise.all(res.map((r) => r.text())));
+          throw new Error("Failed to send traces");
         }
-      });
-      if (!outputRes.ok) {
-        console.error(await outputRes.text());
-        return;
+        const outputTrace = await res[1].json();
+        const traceId = outputTrace.id;
+        this.lastTraceId = traceId;
+        this.options.onSuccess?.(outputTrace);
+        return traceId;
+      } catch (error) {
+        console.error(error);
+        this.options.onFailure?.(error instanceof Error ? error : new Error(String(error)));
+        return void 0;
       }
     }
   }

package/dist/index.d.cts

@@ -1,4 +1,118 @@
 import { StepResult, ToolSet, LanguageModelUsage, GenerateTextResult } from 'ai';
+import { InferOutput, ObjectSchema, SchemaWithPipe, StringSchema, UuidAction, NumberSchema, PicklistSchema, RecordSchema, AnySchema, CustomSchema, StandardProps, UnknownDataset, Config, BaseIssue, OutputDataset, ObjectIssue, NumberIssue, StringIssue, PicklistIssue, RecordIssue, CustomIssue } from 'valibot';
+
+declare const vTraceEntity: ObjectSchema<{
+    readonly id: SchemaWithPipe<readonly [StringSchema<undefined>, UuidAction<string, undefined>]>;
+    readonly userId: StringSchema<undefined>;
+    readonly sessionId: StringSchema<undefined>;
+    readonly model: StringSchema<undefined>;
+    readonly token: NumberSchema<undefined>;
+    readonly content: StringSchema<undefined>;
+    readonly type: PicklistSchema<["input", "output", "error"], undefined>;
+    readonly meta: RecordSchema<StringSchema<undefined>, AnySchema, undefined>;
+    readonly createdAt: SchemaWithPipe<readonly [CustomSchema<unknown, undefined>, StringSchema<undefined>]>;
+    readonly startedAt: SchemaWithPipe<readonly [CustomSchema<unknown, undefined>, StringSchema<undefined>]>;
+    readonly endedAt: SchemaWithPipe<readonly [CustomSchema<unknown, undefined>, StringSchema<undefined>]>;
+}, undefined> & {
+    create: Omit<ObjectSchema<{
+        readonly id: SchemaWithPipe<readonly [StringSchema<undefined>, UuidAction<string, undefined>]>;
+        readonly userId: StringSchema<undefined>;
+        readonly sessionId: StringSchema<undefined>;
+        readonly model: StringSchema<undefined>;
+        readonly token: NumberSchema<undefined>;
+        readonly content: StringSchema<undefined>;
+        readonly type: PicklistSchema<["input", "output", "error"], undefined>;
+        readonly meta: RecordSchema<StringSchema<undefined>, AnySchema, undefined>;
+        readonly createdAt: SchemaWithPipe<readonly [CustomSchema<unknown, undefined>, StringSchema<undefined>]>;
+        readonly startedAt: SchemaWithPipe<readonly [CustomSchema<unknown, undefined>, StringSchema<undefined>]>;
+        readonly endedAt: SchemaWithPipe<readonly [CustomSchema<unknown, undefined>, StringSchema<undefined>]>;
+    }, undefined>, "~types" | "~run" | "~standard" | "entries"> & {
+        readonly entries: Omit<{
+            readonly id: SchemaWithPipe<readonly [StringSchema<undefined>, UuidAction<string, undefined>]>;
+            readonly userId: StringSchema<undefined>;
+            readonly sessionId: StringSchema<undefined>;
+            readonly model: StringSchema<undefined>;
+            readonly token: NumberSchema<undefined>;
+            readonly content: StringSchema<undefined>;
+            readonly type: PicklistSchema<["input", "output", "error"], undefined>;
+            readonly meta: RecordSchema<StringSchema<undefined>, AnySchema, undefined>;
+            readonly createdAt: SchemaWithPipe<readonly [CustomSchema<unknown, undefined>, StringSchema<undefined>]>;
+            readonly startedAt: SchemaWithPipe<readonly [CustomSchema<unknown, undefined>, StringSchema<undefined>]>;
+            readonly endedAt: SchemaWithPipe<readonly [CustomSchema<unknown, undefined>, StringSchema<undefined>]>;
+        }, "id" | "createdAt">;
+        readonly "~standard": StandardProps<{
+            type: "output" | "input" | "error";
+            token: number;
+            content: string;
+            userId: string;
+            model: string;
+            meta: {
+                [x: string]: any;
+            };
+            sessionId: string;
+            startedAt: unknown;
+            endedAt: unknown;
+        }, {
+            type: "output" | "input" | "error";
+            token: number;
+            content: string;
+            userId: string;
+            model: string;
+            meta: {
+                [x: string]: any;
+            };
+            sessionId: string;
+            startedAt: string;
+            endedAt: string;
+        }>;
+        readonly "~run": (dataset: UnknownDataset, config: Config<BaseIssue<unknown>>) => OutputDataset<{
+            type: "output" | "input" | "error";
+            token: number;
+            content: string;
+            userId: string;
+            model: string;
+            meta: {
+                [x: string]: any;
+            };
+            sessionId: string;
+            startedAt: string;
+            endedAt: string;
+        }, ObjectIssue | NumberIssue | StringIssue | PicklistIssue | RecordIssue | CustomIssue>;
+        readonly "~types"?: {
+            readonly input: {
+                type: "output" | "input" | "error";
+                token: number;
+                content: string;
+                userId: string;
+                model: string;
+                meta: {
+                    [x: string]: any;
+                };
+                sessionId: string;
+                startedAt: unknown;
+                endedAt: unknown;
+            };
+            readonly output: {
+                type: "output" | "input" | "error";
+                token: number;
+                content: string;
+                userId: string;
+                model: string;
+                meta: {
+                    [x: string]: any;
+                };
+                sessionId: string;
+                startedAt: string;
+                endedAt: string;
+            };
+            readonly issue: ObjectIssue | NumberIssue | StringIssue | PicklistIssue | RecordIssue | CustomIssue;
+        } | undefined;
+    };
+};
+type TraceEntity = InferOutput<typeof vTraceEntity>;
+declare namespace TraceEntity {
+    type Create = InferOutput<typeof vTraceEntity.create>;
+}
 
 declare namespace LangInsight {
     interface Options {
@@ -9,10 +123,14 @@ declare namespace LangInsight {
             sessionId: string;
             [key: string]: any;
         };
+        onSuccess?: (trace: TraceEntity) => void;
+        onFailure?: (error: Error) => void;
     }
     class CallbackHandler {
         private readonly options;
         private readonly client;
+        /** 最後に送信した output trace の ID */
+        lastTraceId: string | undefined;
         constructor(options: Options);
         /**
          * streamText の onFinish コールバックとして使用
@@ -37,6 +155,8 @@ declare namespace LangInsight {
         /**
          * generateText の結果を送信
          *
+         * @returns output trace の traceId（送信失敗時は undefined）
+         *
          * @example
          * ```ts
          * const handler = new LangInsight.CallbackHandler(options);
@@ -46,11 +166,24 @@ declare namespace LangInsight {
          *   prompt: "Hello!",
          * });
          *
-         * await handler.report(result, { input: "Hello!" });
+         * const traceId = await handler.report(result, { input: "Hello!" });
          * ```
          */
         report(result: GenerateTextResult<ToolSet, any>, params: {
             input: string;
+        }): Promise<string | undefined>;
+        /**
+         * フィードバック（👍/👎）を送信
+         *
+         * @example
+         * ```ts
+         * await handler.score({ traceId, value: 1 }); // 👍
+         * await handler.score({ traceId, value: -1 }); // 👎
+         * ```
+         */
+        score(params: {
+            traceId: string;
+            value: 1 | -1;
         }): Promise<void>;
         private sendTraces;
     }

package/package.json

@@ -2,7 +2,7 @@
   "name": "@langinsight/ai-sdk",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "publishConfig": {
     "access": "public"
   },