@mtharrison/loupe 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import { type ChatModelLike, type LocalLLMTracer, type TraceConfig, type TraceContext, type TraceRequest } from './types';
+export type { ChatModelLike, HierarchyNode, HierarchyResponse, LocalLLMTracer, NormalizedTraceContext, TraceConfig, TraceContext, TraceEvent, TraceFilters, TraceHierarchy, TraceListResponse, TraceMode, TraceRecord, TraceRequest, TraceServer, TraceStatus, TraceSummary, TraceTags, UIReloadEvent, } from './types';
+export declare function isTraceEnabled(): boolean;
+export declare function getLocalLLMTracer(config?: TraceConfig): LocalLLMTracer;
+export declare function startTraceServer(config?: TraceConfig): Promise<{
+    host: string;
+    port: number;
+    url: string;
+}>;
+export declare function recordInvokeStart(context: TraceContext, request: TraceRequest, config?: TraceConfig): string;
+export declare function recordInvokeFinish(traceId: string, response: unknown, config?: TraceConfig): void;
+export declare function recordStreamStart(context: TraceContext, request: TraceRequest, config?: TraceConfig): string;
+export declare function recordStreamChunk(traceId: string, chunk: unknown, config?: TraceConfig): void;
+export declare function recordStreamFinish(traceId: string, chunk: unknown, config?: TraceConfig): void;
+export declare function recordError(traceId: string, error: unknown, config?: TraceConfig): void;
+export declare function __resetLocalLLMTracerForTests(): void;
+export declare function wrapChatModel<TModel extends ChatModelLike<TInput, TOptions, TValue, TChunk>, TInput = any, TOptions = any, TValue = any, TChunk = any>(model: TModel, getContext: () => TraceContext, config?: TraceConfig): TModel;

package/dist/index.js

@@ -0,0 +1,220 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTraceEnabled = isTraceEnabled;
+exports.getLocalLLMTracer = getLocalLLMTracer;
+exports.startTraceServer = startTraceServer;
+exports.recordInvokeStart = recordInvokeStart;
+exports.recordInvokeFinish = recordInvokeFinish;
+exports.recordStreamStart = recordStreamStart;
+exports.recordStreamChunk = recordStreamChunk;
+exports.recordStreamFinish = recordStreamFinish;
+exports.recordError = recordError;
+exports.__resetLocalLLMTracerForTests = __resetLocalLLMTracerForTests;
+exports.wrapChatModel = wrapChatModel;
+const server_1 = require("./server");
+const store_1 = require("./store");
+const ui_build_1 = require("./ui-build");
+const utils_1 = require("./utils");
+let singleton = null;
+function isTraceEnabled() {
+    return (0, utils_1.envFlag)('LLM_TRACE_ENABLED');
+}
+function getLocalLLMTracer(config = {}) {
+    if (!singleton) {
+        singleton = new LocalLLMTracerImpl(config);
+    }
+    else if (config && Object.keys(config).length > 0) {
+        singleton.configure(config);
+    }
+    return singleton;
+}
+function startTraceServer(config = {}) {
+    return getLocalLLMTracer(config).startServer();
+}
+function recordInvokeStart(context, request, config = {}) {
+    return getLocalLLMTracer(config).recordInvokeStart(context, request);
+}
+function recordInvokeFinish(traceId, response, config = {}) {
+    getLocalLLMTracer(config).recordInvokeFinish(traceId, response);
+}
+function recordStreamStart(context, request, config = {}) {
+    return getLocalLLMTracer(config).recordStreamStart(context, request);
+}
+function recordStreamChunk(traceId, chunk, config = {}) {
+    getLocalLLMTracer(config).recordStreamChunk(traceId, chunk);
+}
+function recordStreamFinish(traceId, chunk, config = {}) {
+    getLocalLLMTracer(config).recordStreamFinish(traceId, chunk);
+}
+function recordError(traceId, error, config = {}) {
+    getLocalLLMTracer(config).recordError(traceId, error);
+}
+function __resetLocalLLMTracerForTests() {
+    if (singleton?.uiWatcher) {
+        void singleton.uiWatcher.stop();
+    }
+    if (singleton?.server) {
+        singleton.server.close();
+    }
+    singleton = null;
+}
+function wrapChatModel(model, getContext, config) {
+    if (!model || typeof model.invoke !== 'function' || typeof model.stream !== 'function') {
+        throw new TypeError('wrapChatModel expects a ChatModel-compatible object.');
+    }
+    return {
+        async invoke(input, options) {
+            const tracer = getLocalLLMTracer(config);
+            if (!tracer.isEnabled()) {
+                return model.invoke(input, options);
+            }
+            const traceId = tracer.recordInvokeStart(getContext ? getContext() : {}, { input: input, options: options });
+            try {
+                const response = await model.invoke(input, options);
+                tracer.recordInvokeFinish(traceId, response);
+                return response;
+            }
+            catch (error) {
+                tracer.recordError(traceId, error);
+                throw error;
+            }
+        },
+        async *stream(input, options) {
+            const tracer = getLocalLLMTracer(config);
+            if (!tracer.isEnabled()) {
+                yield* model.stream(input, options);
+                return;
+            }
+            const traceId = tracer.recordStreamStart(getContext ? getContext() : {}, { input: input, options: options });
+            try {
+                const stream = model.stream(input, options);
+                for await (const chunk of stream) {
+                    if (chunk?.type === 'finish') {
+                        tracer.recordStreamFinish(traceId, chunk);
+                    }
+                    else {
+                        tracer.recordStreamChunk(traceId, chunk);
+                    }
+                    yield chunk;
+                }
+            }
+            catch (error) {
+                tracer.recordError(traceId, error);
+                throw error;
+            }
+        },
+    };
+}
+class LocalLLMTracerImpl {
+    config;
+    loggedUrl;
+    server;
+    serverFailed;
+    serverInfo;
+    serverStartPromise;
+    store;
+    uiWatcher;
+    constructor(config = {}) {
+        this.config = {
+            host: '127.0.0.1',
+            maxTraces: 1000,
+            port: 4319,
+            uiHotReload: false,
+        };
+        this.configure(config);
+        this.store = new store_1.TraceStore({ maxTraces: this.config.maxTraces });
+        this.server = null;
+        this.serverInfo = null;
+        this.serverStartPromise = null;
+        this.serverFailed = false;
+        this.loggedUrl = false;
+        this.uiWatcher = null;
+    }
+    configure(config = {}) {
+        if (this.serverInfo && (config.host || config.port)) {
+            return;
+        }
+        this.config = {
+            host: config.host || this.config.host || process.env.LLM_TRACE_HOST || '127.0.0.1',
+            port: Number(config.port || this.config.port || process.env.LLM_TRACE_PORT) || 4319,
+            maxTraces: Number(config.maxTraces || this.config.maxTraces || process.env.LLM_TRACE_MAX_TRACES) || 1000,
+            uiHotReload: typeof config.uiHotReload === 'boolean'
+                ? config.uiHotReload
+                : process.env.LLM_TRACE_UI_HOT_RELOAD
+                    ? (0, utils_1.envFlag)('LLM_TRACE_UI_HOT_RELOAD')
+                    : !process.env.CI && !!process.stdout.isTTY && process.env.NODE_ENV !== 'production' && process.env.NODE_ENV !== 'test',
+        };
+        if (this.store) {
+            this.store.maxTraces = this.config.maxTraces;
+        }
+    }
+    isEnabled() {
+        return isTraceEnabled();
+    }
+    startServer() {
+        if (!this.isEnabled() || this.serverFailed) {
+            return Promise.resolve(this.serverInfo);
+        }
+        if (this.serverInfo) {
+            return Promise.resolve(this.serverInfo);
+        }
+        if (this.serverStartPromise) {
+            return this.serverStartPromise;
+        }
+        this.serverStartPromise = (async () => {
+            try {
+                this.server = (0, server_1.createTraceServer)(this.store, this.config);
+                this.serverInfo = await this.server.start();
+                if (this.serverInfo && !this.uiWatcher) {
+                    this.uiWatcher = await (0, ui_build_1.maybeStartUIWatcher)(() => {
+                        this.server?.broadcast({
+                            timestamp: new Date().toISOString(),
+                            traceId: null,
+                            type: 'ui:reload',
+                        });
+                    }, this.config.uiHotReload);
+                }
+                if (!this.loggedUrl && this.serverInfo) {
+                    this.loggedUrl = true;
+                    process.stdout.write(`[llm-trace] dashboard: ${this.serverInfo.url}\n`);
+                }
+                return this.serverInfo;
+            }
+            catch (error) {
+                this.serverFailed = true;
+                process.stderr.write(`[llm-trace] failed to start dashboard: ${error.message}\n`);
+                return null;
+            }
+            finally {
+                this.serverStartPromise = null;
+            }
+        })();
+        return this.serverStartPromise;
+    }
+    recordInvokeStart(context, request) {
+        void this.startServer();
+        return this.store.recordInvokeStart(context, normaliseRequest(request));
+    }
+    recordInvokeFinish(traceId, response) {
+        this.store.recordInvokeFinish(traceId, (0, utils_1.safeClone)(response));
+    }
+    recordStreamStart(context, request) {
+        void this.startServer();
+        return this.store.recordStreamStart(context, normaliseRequest(request));
+    }
+    recordStreamChunk(traceId, chunk) {
+        this.store.recordStreamChunk(traceId, (0, utils_1.safeClone)(chunk));
+    }
+    recordStreamFinish(traceId, chunk) {
+        this.store.recordStreamFinish(traceId, (0, utils_1.safeClone)(chunk));
+    }
+    recordError(traceId, error) {
+        this.store.recordError(traceId, error);
+    }
+}
+function normaliseRequest(request) {
+    return {
+        input: (0, utils_1.safeClone)(request?.input),
+        options: (0, utils_1.safeClone)(request?.options),
+    };
+}

package/dist/server.d.ts

@@ -0,0 +1,6 @@
+import { type TraceServer } from './types';
+import { TraceStore } from './store';
+export declare function createTraceServer(store: TraceStore, options?: {
+    host?: string;
+    port?: number;
+}): TraceServer;

package/dist/server.js

@@ -0,0 +1,156 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTraceServer = createTraceServer;
+const node_http_1 = __importDefault(require("node:http"));
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const node_url_1 = require("node:url");
+const ui_1 = require("./ui");
+function createTraceServer(store, options = {}) {
+    const host = options.host || '127.0.0.1';
+    const port = Number(options.port) || 4319;
+    const clients = new Set();
+    const server = node_http_1.default.createServer(async (req, res) => {
+        try {
+            const url = new node_url_1.URL(req.url || '/', `http://${req.headers.host || `${host}:${port}`}`);
+            if (req.method === 'GET' && url.pathname === '/') {
+                sendHtml(res, (0, ui_1.renderAppHtml)());
+                return;
+            }
+            if (req.method === 'GET' && url.pathname.startsWith('/assets/')) {
+                await sendAsset(res, url.pathname);
+                return;
+            }
+            if (req.method === 'GET' && url.pathname === '/api/traces') {
+                sendJson(res, 200, store.list(parseFilters(url)));
+                return;
+            }
+            if (req.method === 'GET' && url.pathname === '/api/hierarchy') {
+                sendJson(res, 200, store.hierarchy(parseFilters(url)));
+                return;
+            }
+            if (req.method === 'GET' && url.pathname === '/api/events') {
+                openSse(res, clients);
+                return;
+            }
+            if (req.method === 'DELETE' && url.pathname === '/api/traces') {
+                store.clear();
+                sendJson(res, 200, { ok: true });
+                return;
+            }
+            if (req.method === 'GET' && url.pathname.startsWith('/api/traces/')) {
+                const traceId = decodeURIComponent(url.pathname.slice('/api/traces/'.length));
+                const trace = store.get(traceId);
+                if (!trace) {
+                    sendJson(res, 404, { error: 'Trace not found' });
+                    return;
+                }
+                sendJson(res, 200, trace);
+                return;
+            }
+            sendJson(res, 404, { error: 'Not found' });
+        }
+        catch (error) {
+            sendJson(res, 500, { error: error.message });
+        }
+    });
+    store.on('event', (event) => {
+        broadcast(event);
+    });
+    return {
+        async start() {
+            await new Promise((resolve, reject) => {
+                server.once('error', reject);
+                server.listen(port, host, () => {
+                    server.removeListener('error', reject);
+                    resolve();
+                });
+            });
+            server.unref();
+            return {
+                host,
+                port,
+                url: `http://${host}:${port}`,
+            };
+        },
+        broadcast,
+        close() {
+            for (const client of clients) {
+                client.end();
+            }
+            clients.clear();
+            server.close();
+        },
+    };
+    function broadcast(event) {
+        const payload = `data: ${JSON.stringify(event)}\n\n`;
+        for (const client of clients) {
+            client.write(payload);
+        }
+    }
+}
+function parseFilters(url) {
+    return {
+        search: url.searchParams.get('search') || undefined,
+        status: url.searchParams.get('status') || undefined,
+        kind: url.searchParams.get('kind') || undefined,
+        provider: url.searchParams.get('provider') || undefined,
+        model: url.searchParams.get('model') || undefined,
+        groupBy: url.searchParams.get('groupBy') || undefined,
+        tags: url.searchParams.getAll('tag').concat(url.searchParams.get('tags') || []).filter(Boolean),
+    };
+}
+function sendHtml(res, body) {
+    res.writeHead(200, {
+        'Content-Type': 'text/html; charset=utf-8',
+        'Cache-Control': 'no-store',
+    });
+    res.end(body);
+}
+function sendJson(res, statusCode, body) {
+    res.writeHead(statusCode, {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Cache-Control': 'no-store',
+    });
+    res.end(JSON.stringify(body));
+}
+function openSse(res, clients) {
+    res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache, no-store, must-revalidate',
+        Connection: 'keep-alive',
+    });
+    res.write('\n');
+    clients.add(res);
+    res.on('close', () => clients.delete(res));
+}
+async function sendAsset(res, pathname) {
+    const assetName = pathname.replace(/^\/assets\//, '');
+    const filePath = node_path_1.default.join(__dirname, 'client', assetName);
+    try {
+        const body = await (0, promises_1.readFile)(filePath);
+        res.writeHead(200, {
+            'Content-Type': getContentType(filePath),
+            'Cache-Control': 'no-store',
+        });
+        res.end(body);
+    }
+    catch {
+        sendJson(res, 404, { error: 'Asset not found' });
+    }
+}
+function getContentType(filePath) {
+    if (filePath.endsWith('.css')) {
+        return 'text/css; charset=utf-8';
+    }
+    if (filePath.endsWith('.js')) {
+        return 'application/javascript; charset=utf-8';
+    }
+    if (filePath.endsWith('.svg')) {
+        return 'image/svg+xml';
+    }
+    return 'application/octet-stream';
+}

package/dist/store.d.ts

@@ -0,0 +1,25 @@
+import { EventEmitter } from 'node:events';
+import { type HierarchyResponse, type NormalizedTraceContext, type TraceFilters, type TraceListResponse, type TraceRecord, type TraceRequest } from './types';
+export declare class TraceStore extends EventEmitter {
+    maxTraces: number;
+    order: string[];
+    traces: Map<string, TraceRecord>;
+    constructor(options?: {
+        maxTraces?: number;
+    });
+    recordInvokeStart(context: NormalizedTraceContext | undefined, request: TraceRequest): string;
+    recordInvokeFinish(traceId: string, response: any): void;
+    recordStreamStart(context: NormalizedTraceContext | undefined, request: TraceRequest): string;
+    recordStreamChunk(traceId: string, chunk: any): void;
+    recordStreamFinish(traceId: string, chunk: any): void;
+    recordError(traceId: string, error: unknown): void;
+    list(filters?: TraceFilters): TraceListResponse;
+    get(traceId: string): TraceRecord | null;
+    clear(): void;
+    hierarchy(filters?: TraceFilters): HierarchyResponse;
+    private recordStart;
+    private evictIfNeeded;
+    private cloneTrace;
+    private filteredTraces;
+    private publish;
+}