@mtharrison/loupe 1.1.1 → 1.3.0

package/README.md

@@ -20,6 +20,16 @@ Most tracing tools assume hosted infrastructure, persistent storage, or producti
 - cost rollups when token usage and pricing are available
 - zero external services
 
+## Screenshots
+
+Conversation view with tool calls, staged traces, and session navigation:
+
+![Loupe conversation view](./assets/screenshot1.png)
+
+Request view showing the captured OpenAI payload for a multi-turn tool call:
+
+![Loupe request view](./assets/screenshot2.png)
+
 ## Installation
 
 ```sh
@@ -38,15 +48,115 @@ Enable tracing:
 export LLM_TRACE_ENABLED=1
 ```
 
+If your app already uses a higher-level model interface or the official OpenAI client, Loupe can wrap that directly instead of requiring manual `record*` calls.
+
+### `wrapOpenAIClient(client, getContext, config?)`
+
+Wraps `client.chat.completions.create(...)` on an OpenAI-compatible client and records either an `invoke` trace or a `stream` trace based on `params.stream`.
+
+```ts
+import {
+  wrapOpenAIClient,
+} from '@mtharrison/loupe';
+import OpenAI from 'openai';
+
+const client = wrapOpenAIClient(
+  new OpenAI(),
+  () => ({
+    sessionId: 'session-123',
+    rootActorId: 'support-assistant',
+    actorId: 'support-assistant',
+  }),
+);
+
+const completion = await client.chat.completions.create({
+  model: 'gpt-4.1',
+  messages: [{ role: 'user', content: 'Summarize the latest notes.' }],
+});
+
+const stream = await client.chat.completions.create({
+  model: 'gpt-4.1',
+  messages: [{ role: 'user', content: 'Stream the same summary.' }],
+  stream: true,
+});
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices?.[0]?.delta?.content || '');
+}
+```
+
+If you do not call `startServer()` yourself, the dashboard starts lazily on the first recorded trace.
+
+When the server starts, Loupe prints the local URL:
+
+```text
+[llm-trace] dashboard: http://127.0.0.1:4319
+```
+
+If `4319` is already in use and you did not explicitly configure a port, Loupe falls back to another free local port and prints that URL instead.
+
+`wrapOpenAIClient()` is structurally typed, so Loupe's runtime API does not require the OpenAI SDK for normal library usage. The repo includes `openai` as a dev dependency for the bundled demo; if your own app instantiates `new OpenAI()` or runs the published example from a consumer install, install `openai` there too.
+
+### `wrapChatModel(model, getContext, config?)`
+
+Wraps any object with `invoke()` and `stream()` methods.
+
+### Runnable OpenAI Tools Demo
+
+There is also a runnable example at `examples/openai-multiturn-tools.js` that:
+
+- starts the Loupe dashboard eagerly
+- wraps an OpenAI client with `wrapOpenAIClient()`
+- runs a multi-turn conversation with tool calls
+- keeps the process alive so the in-memory traces stay visible in the dashboard
+
+From this repo, after installing this package's dev dependencies, run:
+
+```bash
+npm install
+export OPENAI_API_KEY=your-key
+export LLM_TRACE_ENABLED=1
+node examples/openai-multiturn-tools.js
+```
+
+If you copy this example pattern into another app, install `openai` in that app before using `new OpenAI()`.
+
+Supported demo environment variables: `OPENAI_MODEL`, `LLM_TRACE_PORT`, `LOUPE_OPEN_BROWSER`.
+
+The script tries to open the dashboard automatically and prints the local URL either way. Set `LOUPE_OPEN_BROWSER=0` if you want to suppress the browser launch.
+
+### Runnable Nested Tool-Call Demo
+
+`examples/nested-tool-call.js` is a credential-free demo that:
+
+- starts the Loupe dashboard eagerly
+- wraps a root assistant model and a nested tool model
+- invokes the nested tool model from inside the parent model call
+- shows parent/child spans linked on the same trace
+
+Run it with:
+
+```bash
+npm install
+export LLM_TRACE_ENABLED=1
+node examples/nested-tool-call.js
+```
+
+## Low-Level Lifecycle API
+
+If you need full control over trace boundaries, Loupe exposes a lower-level span lifecycle API modeled on OpenTelemetry concepts: start a span, add events, end it, and record exceptions.
+
+Loupe stores GenAI span attributes using the OpenTelemetry semantic convention names where they apply, including `gen_ai.request.model`, `gen_ai.response.model`, `gen_ai.system`, `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, and `gen_ai.conversation.id`.
+
 Start the dashboard during app startup, then instrument a model call:
 
 ```ts
 import {
   getLocalLLMTracer,
   isTraceEnabled,
-  recordError,
-  recordInvokeFinish,
-  recordInvokeStart,
+  endSpan,
+  recordException,
+  startSpan,
   type TraceContext,
 } from '@mtharrison/loupe';
 
@@ -75,59 +185,63 @@ const request = {
   options: {},
 };
 
-const traceId = recordInvokeStart(context, request);
+const spanId = startSpan(context, {
+  mode: 'invoke',
+  name: 'openai.chat.completions',
+  request,
+});
 
 try {
   const response = await model.invoke(request.input, request.options);
-  recordInvokeFinish(traceId, response);
+  endSpan(spanId, response);
   return response;
 } catch (error) {
-  recordError(traceId, error);
+  recordException(spanId, error);
   throw error;
 }
 ```
 
-If you do not call `startServer()` yourself, the dashboard starts lazily on the first recorded trace.
-
-When the server starts, Loupe prints the local URL:
-
-```text
-[llm-trace] dashboard: http://127.0.0.1:4319
-```
-
-## Streaming
+### Streaming
 
-Streaming works the same way. Loupe records each chunk event, first-chunk latency, and the reconstructed final response.
+Streaming works the same way. Loupe records each span event, first-chunk latency, and the reconstructed final response.
 
 ```ts
 import {
-  recordError,
-  recordStreamChunk,
-  recordStreamFinish,
-  recordStreamStart,
+  addSpanEvent,
+  endSpan,
+  recordException,
+  startSpan,
 } from '@mtharrison/loupe';
 
-const traceId = recordStreamStart(context, request);
+const spanId = startSpan(context, {
+  mode: 'stream',
+  name: 'openai.chat.completions',
+  request,
+});
 
 try {
   for await (const chunk of model.stream(request.input, request.options)) {
     if (chunk?.type === 'finish') {
-      recordStreamFinish(traceId, chunk);
+      endSpan(spanId, chunk);
     } else {
-      recordStreamChunk(traceId, chunk);
+      addSpanEvent(spanId, {
+        name: `stream.${chunk?.type || 'event'}`,
+        attributes: chunk,
+        payload: chunk,
+      });
     }
 
     yield chunk;
   }
 } catch (error) {
-  recordError(traceId, error);
+  recordException(spanId, error);
   throw error;
 }
 ```
 
 ## Trace Context
 
-Loupe gets its hierarchy and filters from the context you pass to `recordInvokeStart()` and `recordStreamStart()`.
+Loupe gets its hierarchy and filters from the context you pass to `startSpan()`.
 
 ### Generic context fields
 
@@ -213,7 +327,7 @@ If usage or pricing is missing, Loupe still records the trace, but cost will sho
 
 The local dashboard includes:
 
-- `Traces` and `Sessions` navigation
+- session-first tree navigation
 - hierarchy-aware browsing
 - conversation, request, response, context, and stream views
 - formatted and raw JSON modes
@@ -231,7 +345,7 @@ Environment variables:
 | --- | --- | --- |
 | `LLM_TRACE_ENABLED` | `false` | Enables Loupe. |
 | `LLM_TRACE_HOST` | `127.0.0.1` | Host for the local dashboard server. |
-| `LLM_TRACE_PORT` | `4319` | Port for the local dashboard server. |
+| `LLM_TRACE_PORT` | `4319` | Port for the local dashboard server. If unset, Loupe tries `4319` first and falls back to a free local port if it is already in use. |
 | `LLM_TRACE_MAX_TRACES` | `1000` | Maximum number of traces kept in memory. |
 | `LLM_TRACE_UI_HOT_RELOAD` | auto in local interactive dev | Enables UI rebuild + reload while developing the dashboard itself. |
 
@@ -239,7 +353,7 @@ Programmatic configuration is also available through `getLocalLLMTracer(config)`
 
 ## API
 
-The supported public API is the low-level tracer lifecycle API.
+Loupe exposes both low-level span lifecycle functions and lightweight wrappers.
 
 ### `isTraceEnabled()`
 
@@ -257,31 +371,31 @@ Returns the singleton tracer instance. This is useful if you want to:
 
 Starts the local dashboard server eagerly instead of waiting for the first trace.
 
-### `recordInvokeStart(context, request, config?)`
+### `startSpan(context, options?, config?)`
 
-Creates an `invoke` trace and returns a `traceId`.
+Creates a span and returns its Loupe `spanId`. Pass `mode`, `name`, and `request` in `options` to describe the operation. Nested spans are linked automatically when wrapped calls invoke other wrapped calls in the same async flow.
 
-### `recordInvokeFinish(traceId, response, config?)`
+### `addSpanEvent(spanId, event, config?)`
 
-Marks an `invoke` trace as complete and stores the response payload.
+Appends an event to an existing span. For streaming traces, pass the raw chunk as `event.payload` to preserve chunk reconstruction in the UI.
 
-### `recordStreamStart(context, request, config?)`
+### `endSpan(spanId, response, config?)`
 
-Creates a `stream` trace and returns a `traceId`.
+Marks a span as complete and stores the final response payload.
 
-### `recordStreamChunk(traceId, chunk, config?)`
+### `recordException(spanId, error, config?)`
 
-Appends a non-final stream chunk to an existing trace.
+Marks a span as failed and stores a serialized exception payload.
 
-### `recordStreamFinish(traceId, chunk, config?)`
+All of these functions forward to the singleton tracer returned by `getLocalLLMTracer()`.
 
-Stores the final stream payload and marks the trace complete.
+### `wrapChatModel(model, getContext, config?)`
 
-### `recordError(traceId, error, config?)`
+Returns a traced model wrapper for `invoke()` and `stream()`.
 
-Marks a trace as failed and stores a serialized error payload.
+### `wrapOpenAIClient(client, getContext, config?)`
 
-All of these functions forward to the singleton tracer returned by `getLocalLLMTracer()`.
+Returns a traced OpenAI client wrapper for `chat.completions.create(...)`.
 
 ## HTTP Endpoints