@warpmetrics/warp 0.0.17 → 0.0.19

package/README.md

@@ -14,7 +14,7 @@ npm install @warpmetrics/warp
 
 ```js
 import OpenAI from 'openai';
-import { warp, run, group, call, outcome } from '@warpmetrics/warp';
+import { warp, run, group, call, trace, outcome } from '@warpmetrics/warp';
 
 const openai = warp(new OpenAI(), { apiKey: 'wm_...' });
 
@@ -90,6 +90,38 @@ call(r, response);
 call(g, response, { label: 'extract' });  // with opts
 ```
 
+### `trace(target, data)`
+
+Manually record an LLM call for providers not wrapped by `warp()`.
+
+```js
+trace(r, {
+  provider: 'google',
+  model: 'gemini-2.0-flash',
+  messages: [{ role: 'user', content: 'Hello' }],
+  response: 'Hi there!',
+  tokens: { prompt: 10, completion: 5 },
+  latency: 230,
+  cost: 0.0001,
+});
+```
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `provider` | `string` | Yes | Provider name (e.g. `"google"`, `"cohere"`) |
+| `model` | `string` | Yes | Model identifier |
+| `messages` | `any` | No | Request messages/input |
+| `response` | `string` | No | Response text |
+| `tools` | `string[]` | No | Tool names available |
+| `toolCalls` | `{ id, name, arguments }[]` | No | Tool calls made |
+| `tokens` | `{ prompt?, completion?, total? }` | No | Token usage |
+| `latency` | `number` | No | Duration in milliseconds |
+| `timestamp` | `string` | No | ISO 8601 timestamp (auto-generated if omitted) |
+| `status` | `string` | No | `"success"` (default) or `"error"` |
+| `error` | `string` | No | Error message |
+| `cost` | `number` | No | Cost in USD |
+| `opts` | `Record<string, any>` | No | Custom metadata |
+
 ### `outcome(target, name, opts?)`
 
 Record an outcome on any tracked target.
@@ -110,11 +142,12 @@ const r2 = run(a, 'Code Review');
 
 ### `ref(target)`
 
-Resolve any target (run, group, or LLM response) to its string ID.
+Resolve any target (run, group, outcome, act, or LLM response) to its string ID. Also accepts raw ID strings (e.g. `"wm_run_..."` loaded from a database) and registers them locally.
 
 ```js
 ref(r)         // 'wm_run_01jkx3ndek0gh4r5tmqp9a3bcv'
 ref(response)  // 'wm_call_01jkx3ndef8mn2q7kpvhc4e9ws'
+ref('wm_run_01jkx3ndek0gh4r5tmqp9a3bcv')  // adopts and returns the ID
 ```
 
 ### `flush()`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpmetrics/warp",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "description": "Measure your agents, not your LLM calls.",
   "type": "module",
   "main": "src/index.js",

package/src/core/transport.js

@@ -166,7 +166,7 @@ export function logRun(data) {
     label: data.label,
     opts: data.opts || null,
     refId: data.refId || null,
-    timestamp: new Date().toISOString(),
+    startedAt: data.startedAt || new Date().toISOString(),
   });
 }
 
@@ -175,7 +175,7 @@ export function logGroup(data) {
     id: data.id,
     label: data.label,
     opts: data.opts || null,
-    timestamp: new Date().toISOString(),
+    startedAt: data.startedAt || new Date().toISOString(),
   });
 }
 

package/src/core/warp.js

@@ -32,13 +32,14 @@ function createInterceptor(originalFn, context, provider) {
 
     try {
       const result  = await originalFn.apply(context, args);
-      const latency = Date.now() - start;
+      const duration = Date.now() - start;
 
       if (stream) {
         return wrapStream(result, { callId, provider, model, messages, tools, start });
       }
 
       const ext  = provider.extract(result);
+      const endedAt = new Date().toISOString();
 
       responseRegistry.set(result, {
         id: callId,
@@ -47,8 +48,9 @@ function createInterceptor(originalFn, context, provider) {
           response: ext.response,
           tools: tools ? tools.map(t => t.function?.name || t.name).filter(Boolean) : null,
           toolCalls: ext.toolCalls,
-          tokens: ext.tokens, latency,
-          timestamp: new Date().toISOString(),
+          tokens: ext.tokens, duration,
+          startedAt: new Date(start).toISOString(),
+          endedAt,
           status: 'success',
         },
       });
@@ -56,13 +58,15 @@ function createInterceptor(originalFn, context, provider) {
       return result;
     } catch (error) {
       const errorResult = { _warpError: true };
+      const duration = Date.now() - start;
       responseRegistry.set(errorResult, {
         id: callId,
         data: {
           id: callId, provider: provider.name, model, messages,
           error: error.message,
-          latency: Date.now() - start,
-          timestamp: new Date().toISOString(),
+          duration,
+          startedAt: new Date(start).toISOString(),
+          endedAt: new Date().toISOString(),
           status: 'error',
         },
       });
@@ -95,6 +99,7 @@ function wrapStream(stream, ctx) {
         ? ctx.provider.normalizeUsage(usage)
         : { prompt: 0, completion: 0, total: 0 };
 
+      const duration = Date.now() - ctx.start;
       responseRegistry.set(wrapped, {
         id: ctx.callId,
         data: {
@@ -102,8 +107,9 @@ function wrapStream(stream, ctx) {
           response: content,
           tools: ctx.tools ? ctx.tools.map(t => t.function?.name || t.name).filter(Boolean) : null,
           tokens,
-          latency: Date.now() - ctx.start,
-          timestamp: new Date().toISOString(),
+          duration,
+          startedAt: new Date(ctx.start).toISOString(),
+          endedAt: new Date().toISOString(),
           status: 'success',
         },
       });

package/src/index.d.ts

@@ -47,6 +47,45 @@ export function group(target: Run | Group | string, label: string, opts?: Record
 /** Track an LLM call by linking a response to a run or group. */
 export function call(target: Run | Group | string, response: object, opts?: Record<string, any>): void;
 
+export interface TraceData {
+  /** Provider name (e.g. "google", "cohere"). */
+  provider: string;
+  /** Model identifier. */
+  model: string;
+  /** Request messages/input. */
+  messages?: any;
+  /** Response text. */
+  response?: string;
+  /** Tool names available. */
+  tools?: string[];
+  /** Tool calls made. */
+  toolCalls?: { id?: string; name: string; arguments?: string }[];
+  /** Token usage. */
+  tokens?: { prompt?: number; completion?: number; total?: number };
+  /** Duration in milliseconds. */
+  duration?: number;
+  /** ISO 8601 timestamp of when the call started. */
+  startedAt?: string;
+  /** ISO 8601 timestamp of when the call ended (auto-generated if omitted). */
+  endedAt?: string;
+  /** "success" (default) or "error". */
+  status?: string;
+  /** Error message. */
+  error?: string;
+  /** Cost in USD. */
+  cost?: number;
+  /** Custom metadata. */
+  opts?: Record<string, any>;
+}
+
+export interface Call {
+  readonly id: string;
+  readonly _type: 'call';
+}
+
+/** Manually record an LLM call for providers not wrapped by warp(). */
+export function trace(target: Run | Group | string, data: TraceData): Call | undefined;
+
 /** Record an outcome on any tracked target. Returns an Outcome handle for use with act(). */
 export function outcome(
   target: Run | Group | object | string,

package/src/trace/group.js

@@ -14,6 +14,7 @@ import { logGroup, logLink, getConfig } from '../core/transport.js';
  * @returns {{ readonly id: string, readonly _type: 'group' }}
  */
 export function group(target, label, opts) {
+  const startedAt = new Date().toISOString();
   const targetId = getRef(target);
   if (!targetId) {
     if (getConfig().debug) console.warn('[warpmetrics] group() — target not recognised.');
@@ -29,6 +30,7 @@ export function group(target, label, opts) {
     label,
     opts: opts || null,
     parentId: targetId,
+    startedAt,
     groups: [],
     calls: [],
   };

package/src/trace/run.js

@@ -14,6 +14,7 @@ import { logRun, getConfig } from '../core/transport.js';
  * @returns {{ readonly id: string, readonly _type: 'run' }}
  */
 export function run(labelOrRef, labelOrOpts, maybeOpts) {
+  const startedAt = new Date().toISOString();
   let refId = null;
   let label, opts;
 
@@ -37,6 +38,7 @@ export function run(labelOrRef, labelOrOpts, maybeOpts) {
     label,
     opts,
     refId,
+    startedAt,
     groups: [],
     calls: [],
   };

package/src/trace/trace.js

@@ -26,6 +26,10 @@ export function trace(target, data) {
 
   const id = generateId('call');
 
+  const endedAt = data.endedAt || data.timestamp || new Date().toISOString();
+  const duration = data.duration ?? data.latency ?? null;
+  const startedAt = data.startedAt || (duration != null ? new Date(new Date(endedAt).getTime() - duration).toISOString() : endedAt);
+
   const event = {
     id,
     provider: data.provider,
@@ -35,8 +39,9 @@ export function trace(target, data) {
     tools: data.tools || null,
     toolCalls: data.toolCalls || null,
     tokens: data.tokens || null,
-    latency: data.latency ?? null,
-    timestamp: data.timestamp || new Date().toISOString(),
+    duration,
+    startedAt,
+    endedAt,
     status: data.status || 'success',
   };