@posthog/ai 7.16.15 → 7.17.0

package/README.md

@@ -39,6 +39,37 @@ console.log(completion.choices[0].message.content)
 await phClient.shutdown()
 ```
 
+## Custom and unsupported providers
+
+For LLM calls that don't go through one of the wrapped clients — direct Cloudflare Workers AI bindings, TanStack AI adapters, custom HTTP clients — use `captureAiGeneration` to emit the same `$ai_generation` events the wrappers produce.
+
+```typescript
+import { captureAiGeneration } from '@posthog/ai'
+import { PostHog } from 'posthog-node'
+
+const phClient = new PostHog('<YOUR_PROJECT_API_KEY>', { host: 'https://us.i.posthog.com' })
+
+const start = Date.now()
+const result = await env.AI.run('@cf/zai-org/glm-4.7-flash', { messages, reasoning_effort: 'high' })
+
+await captureAiGeneration(phClient, {
+  distinctId: 'user_123',
+  traceId: 'trace_abc',
+  provider: 'cloudflare-workers-ai',
+  model: '@cf/zai-org/glm-4.7-flash',
+  input: messages,
+  output: result.response,
+  modelParameters: { reasoning_effort: 'high' },
+  usage: { inputTokens: result.usage?.prompt_tokens, outputTokens: result.usage?.completion_tokens },
+  latency: (Date.now() - start) / 1000,
+  properties: { feature: 'transcript-toc' },
+})
+
+await phClient.shutdown()
+```
+
+`captureAiGeneration` is the same primitive that every other `@posthog/ai` wrapper funnels through, so the resulting events are indistinguishable from those produced by `withTracing`, `OpenAI`, `Anthropic`, etc.
+
 ## OpenTelemetry
 
 `@posthog/ai/otel` provides two ways to send AI traces to PostHog via OpenTelemetry. Both automatically filter to AI-related spans only (`gen_ai.*`, `llm.*`, `ai.*`, `traceloop.*`) and PostHog converts them into `$ai_generation` events server-side. This works with any LLM provider SDK that supports OpenTelemetry.

package/dist/anthropic/index.cjs

@@ -10,8 +10,6 @@ function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var AnthropicOriginal__default = /*#__PURE__*/_interopDefault(AnthropicOriginal);
 
-var version = "7.16.15";
-
 // Type guards for safer type checking
 
 const isObject = value => {
@@ -211,73 +209,69 @@ function addDefaults(params) {
     traceId: params.traceId ?? uuid.v4()
   };
 }
-const sendEventWithErrorToPosthog = async ({
-  client,
-  traceId,
-  error,
-  ...args
-}) => {
-  const httpStatus = error && typeof error === 'object' && 'status' in error ? error.status ?? 500 : 500;
-  const properties = {
-    client,
-    traceId,
-    httpStatus,
-    error: JSON.stringify(error),
-    ...args
-  };
-  const enrichedError = error;
-  if (client.options?.enableExceptionAutocapture) {
-    // assign a uuid that can be used to link the trace and exception events
-    const exceptionId = core.uuidv7();
-    client.captureException(error, undefined, {
-      $ai_trace_id: traceId
-    }, exceptionId);
-    enrichedError.__posthog_previously_captured_error = true;
-    properties.exceptionId = exceptionId;
-  }
-  await sendEventToPosthog(properties);
-  return enrichedError;
-};
-const sendEventToPosthog = async ({
-  client,
-  eventType = AIEvent.Generation,
-  distinctId,
-  traceId,
-  model,
-  provider,
-  input,
-  output,
-  latency,
-  timeToFirstToken,
-  baseURL,
-  params,
-  httpStatus = 200,
-  usage = {},
-  error,
-  exceptionId,
-  stopReason,
-  tools,
-  captureImmediate = false
-}) => {
+
+var version = "7.17.0";
+
+/**
+ * Options for `captureAiGeneration`. Mirrors the `$ai_generation` event shape
+ * directly so that any caller — first-party SDK wrappers and external code
+ * alike — produces an identical event.
+ */
+
+/**
+ * Capture an `$ai_generation` (or `$ai_embedding`) event to PostHog.
+ *
+ * This is the canonical primitive that every `@posthog/ai` wrapper
+ * (`withTracing`, `OpenAI`, `Anthropic`, `GoogleGenAI`, …) funnels through, so
+ * external code can use it directly to instrument LLM calls made through
+ * arbitrary clients (Cloudflare Workers AI, custom HTTP, etc.) and get the
+ * same events the SDK wrappers produce.
+ *
+ * When `error` is set, the event is captured as an error. If the error is an
+ * object, it is mutated in place to set `__posthog_previously_captured_error`
+ * so callers can re-throw the original error reference safely.
+ */
+const captureAiGeneration = async (client, options) => {
   if (!client.capture) {
-    return Promise.resolve();
+    return;
   }
-  // sanitize input and output for UTF-8 validity
-  const safeInput = sanitizeValues(input);
-  const safeOutput = sanitizeValues(output);
-  const safeError = sanitizeValues(error);
+  const traceId = options.traceId ?? uuid.v4();
+  const eventType = options.eventType ?? AIEvent.Generation;
+  const privacyMode = options.privacyMode ?? false;
+  const usage = options.usage ?? {};
+  const safeInput = sanitizeValues(options.input);
+  const safeOutput = sanitizeValues(options.output);
+  let httpStatus = options.httpStatus;
   let errorData = {};
-  if (error) {
+  if (options.error) {
+    if (httpStatus === undefined) {
+      if (typeof options.error === 'object' && 'status' in options.error && typeof options.error.status === 'number') {
+        httpStatus = options.error.status;
+      } else {
+        httpStatus = 500;
+      }
+    }
+    let exceptionId;
+    if (client.options?.enableExceptionAutocapture) {
+      exceptionId = core.uuidv7();
+      client.captureException(options.error, undefined, {
+        $ai_trace_id: traceId
+      }, exceptionId);
+      if (typeof options.error === 'object') {
+        options.error.__posthog_previously_captured_error = true;
+      }
+    }
     errorData = {
       $ai_is_error: true,
-      $ai_error: safeError,
+      $ai_error: sanitizeValues(JSON.stringify(options.error)),
       $exception_event_id: exceptionId
     };
   }
+  httpStatus = httpStatus ?? 200;
   let costOverrideData = {};
-  if (params.posthogCostOverride) {
-    const inputCostUSD = (params.posthogCostOverride.inputCost ?? 0) * (usage.inputTokens ?? 0);
-    const outputCostUSD = (params.posthogCostOverride.outputCost ?? 0) * (usage.outputTokens ?? 0);
+  if (options.costOverride) {
+    const inputCostUSD = (options.costOverride.inputCost ?? 0) * (usage.inputTokens ?? 0);
+    const outputCostUSD = (options.costOverride.outputCost ?? 0) * (usage.outputTokens ?? 0);
     costOverrideData = {
       $ai_input_cost_usd: inputCostUSD,
       $ai_output_cost_usd: outputCostUSD,
@@ -304,50 +298,48 @@ const sendEventToPosthog = async ({
   const properties = {
     $ai_lib: 'posthog-ai',
     $ai_lib_version: version,
-    $ai_provider: params.posthogProviderOverride ?? provider,
-    $ai_model: params.posthogModelOverride ?? model,
-    $ai_model_parameters: getModelParams(params),
-    $ai_input: withPrivacyMode(client, params.posthogPrivacyMode ?? false, safeInput),
-    $ai_output_choices: withPrivacyMode(client, params.posthogPrivacyMode ?? false, safeOutput),
+    $ai_provider: options.providerOverride ?? options.provider,
+    $ai_model: options.modelOverride ?? options.model,
+    $ai_model_parameters: options.modelParameters ?? {},
+    $ai_input: withPrivacyMode(client, privacyMode, safeInput),
+    $ai_output_choices: withPrivacyMode(client, privacyMode, safeOutput),
     $ai_http_status: httpStatus,
     $ai_input_tokens: usage.inputTokens ?? 0,
     ...(usage.outputTokens !== undefined ? {
       $ai_output_tokens: usage.outputTokens
     } : {}),
     ...additionalTokenValues,
-    $ai_latency: latency,
-    ...(timeToFirstToken !== undefined ? {
-      $ai_time_to_first_token: timeToFirstToken
+    $ai_latency: options.latency ?? 0,
+    ...(options.timeToFirstToken !== undefined ? {
+      $ai_time_to_first_token: options.timeToFirstToken
     } : {}),
     $ai_trace_id: traceId,
-    $ai_base_url: baseURL,
-    ...params.posthogProperties,
-    $ai_tokens_source: getTokensSource(params.posthogProperties),
-    ...(distinctId ? {} : {
+    $ai_base_url: options.baseURL ?? '',
+    ...options.properties,
+    $ai_tokens_source: getTokensSource(options.properties),
+    ...(options.distinctId ? {} : {
       $process_person_profile: false
     }),
-    ...(stopReason ? {
-      $ai_stop_reason: stopReason
+    ...(options.stopReason ? {
+      $ai_stop_reason: options.stopReason
     } : {}),
-    ...(tools ? {
-      $ai_tools: tools
+    ...(options.tools ? {
+      $ai_tools: options.tools
     } : {}),
     ...errorData,
     ...costOverrideData
   };
   const event = {
-    distinctId: distinctId ?? traceId,
+    distinctId: options.distinctId ?? traceId,
     event: eventType,
     properties,
-    groups: params.posthogGroups
+    groups: options.groups
   };
-  if (captureImmediate) {
-    // await capture promise to send single event in serverless environments
+  if (options.captureImmediate) {
     await client.captureImmediate(event);
   } else {
     client.capture(event);
   }
-  return Promise.resolve();
 };
 
 class PostHogAnthropic extends AnthropicOriginal__default.default {
@@ -509,8 +501,7 @@ class WrappedMessages extends AnthropicOriginal__default.default.Messages {
                   text: accumulatedContent
                 }]
               }];
-              await sendEventToPosthog({
-                client: this.phClient,
+              await captureAiGeneration(this.phClient, {
                 ...posthogParams,
                 model: anthropicParams.model,
                 provider: 'anthropic',
@@ -519,15 +510,14 @@ class WrappedMessages extends AnthropicOriginal__default.default.Messages {
                 latency,
                 timeToFirstToken,
                 baseURL: this.baseURL,
-                params: body,
+                modelParameters: getModelParams(body),
                 httpStatus: 200,
                 usage,
                 stopReason,
                 tools: availableTools
               });
             } catch (error) {
-              const enrichedError = await sendEventWithErrorToPosthog({
-                client: this.phClient,
+              await captureAiGeneration(this.phClient, {
                 ...posthogParams,
                 model: anthropicParams.model,
                 provider: 'anthropic',
@@ -535,14 +525,14 @@ class WrappedMessages extends AnthropicOriginal__default.default.Messages {
                 output: [],
                 latency: 0,
                 baseURL: this.baseURL,
-                params: body,
+                modelParameters: getModelParams(body),
                 usage: {
                   inputTokens: 0,
                   outputTokens: 0
                 },
                 error: error
               });
-              throw enrichedError;
+              throw error;
             }
           })();
 
@@ -556,8 +546,7 @@ class WrappedMessages extends AnthropicOriginal__default.default.Messages {
         if ('content' in result) {
           const latency = (Date.now() - startTime) / 1000;
           const availableTools = extractAvailableToolCalls('anthropic', anthropicParams);
-          await sendEventToPosthog({
-            client: this.phClient,
+          await captureAiGeneration(this.phClient, {
             ...posthogParams,
             model: anthropicParams.model,
             provider: 'anthropic',
@@ -565,7 +554,7 @@ class WrappedMessages extends AnthropicOriginal__default.default.Messages {
             output: formatResponseAnthropic(result),
             latency,
             baseURL: this.baseURL,
-            params: body,
+            modelParameters: getModelParams(body),
             httpStatus: 200,
             usage: {
               inputTokens: result.usage.input_tokens ?? 0,
@@ -581,8 +570,7 @@ class WrappedMessages extends AnthropicOriginal__default.default.Messages {
         }
         return result;
       }, async error => {
-        await sendEventToPosthog({
-          client: this.phClient,
+        await captureAiGeneration(this.phClient, {
           ...posthogParams,
           model: anthropicParams.model,
           provider: 'anthropic',
@@ -590,13 +578,13 @@ class WrappedMessages extends AnthropicOriginal__default.default.Messages {
           output: [],
           latency: 0,
           baseURL: this.baseURL,
-          params: body,
+          modelParameters: getModelParams(body),
           httpStatus: error?.status ? error.status : 500,
           usage: {
             inputTokens: 0,
             outputTokens: 0
           },
-          error: JSON.stringify(error)
+          error: error
         });
         throw error;
       });