npm - @mtharrison/loupe - Versions diffs - 1.0.0 - Mend

@mtharrison/loupe 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

package/dist/ui-build.js ADDED Viewed

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildUIAssets = buildUIAssets;
+exports.maybeStartUIWatcher = maybeStartUIWatcher;
+const esbuild_1 = require("esbuild");
+const node_path_1 = __importDefault(require("node:path"));
+const utils_1 = require("./utils");
+const rootDir = node_path_1.default.resolve(__dirname, '..');
+const outdir = node_path_1.default.join(__dirname, 'client');
+const entryPoint = node_path_1.default.join(rootDir, 'client', 'main.tsx');
+function createBuildOptions() {
+    return {
+        entryNames: 'app',
+        entryPoints: [entryPoint],
+        bundle: true,
+        outdir,
+        format: 'esm',
+        platform: 'browser',
+        target: ['es2022'],
+        jsx: 'automatic',
+        loader: {
+            '.svg': 'dataurl',
+        },
+        splitting: false,
+        minify: false,
+        sourcemap: false,
+        logLevel: 'silent',
+    };
+}
+async function buildUIAssets() {
+    await (0, esbuild_1.build)(createBuildOptions());
+}
+async function maybeStartUIWatcher(onReload, enabled) {
+    const watchEnabled = typeof enabled === 'boolean'
+        ? enabled
+        : 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 (!watchEnabled) {
+        return null;
+    }
+    const buildContext = await (0, esbuild_1.context)({
+        ...createBuildOptions(),
+        plugins: [
+            {
+                name: 'llm-trace-hot-reload',
+                setup(build) {
+                    build.onEnd((result) => {
+                        if (!result.errors.length) {
+                            onReload();
+                        }
+                    });
+                },
+            },
+        ],
+    });
+    await buildContext.watch();
+    return {
+        async stop() {
+            await buildContext.dispose();
+        },
+    };
+}

package/dist/ui.d.ts ADDED Viewed

	@@ -0,0 +1 @@
1	+ export declare function renderAppHtml(): string;

package/dist/ui.js ADDED Viewed

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderAppHtml = renderAppHtml;
+const brand_1 = require("./brand");
+const theme_1 = require("./theme");
+function renderAppHtml() {
+    const brandIcon = (0, brand_1.renderBrandMarkSvg)();
+    const faviconHref = `data:image/svg+xml,${encodeURIComponent(brandIcon)}`;
+    const themeBootstrapScript = (0, theme_1.renderThemeBootstrapScript)();
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${brand_1.BRAND_NAME}</title>
+    <link rel="icon" href="${faviconHref}" />
+    <script>${themeBootstrapScript}</script>
+    <link rel="stylesheet" href="/assets/app.css" />
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/assets/app.js"></script>
+  </body>
+</html>`;
+}

package/dist/utils.d.ts ADDED Viewed

@@ -0,0 +1,10 @@
+import { type NormalizedTraceContext, type TraceContext, type TraceMode, type TraceRecord, type TraceSummary } from './types';
+export declare function safeClone<T>(value: T): T;
+export declare function toErrorPayload(error: any): Record<string, any> | null;
+export declare function sanitizeHeaders(headers: Record<string, any> | undefined): Record<string, any>;
+export declare function envFlag(name: string): boolean;
+export declare function stringifyRecord(record: Record<string, any>): Record<string, string>;
+export declare function normalizeTraceContext(context: TraceContext | undefined, mode: TraceMode): NormalizedTraceContext;
+export declare function summariseValue(value: unknown, maxLength?: number): string;
+export declare function getUsageCostUsd(usage: Record<string, any> | null | undefined): number | null;
+export declare function toSummary(trace: TraceRecord): TraceSummary;

package/dist/utils.js ADDED Viewed

@@ -0,0 +1,280 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeClone = safeClone;
+exports.toErrorPayload = toErrorPayload;
+exports.sanitizeHeaders = sanitizeHeaders;
+exports.envFlag = envFlag;
+exports.stringifyRecord = stringifyRecord;
+exports.normalizeTraceContext = normalizeTraceContext;
+exports.summariseValue = summariseValue;
+exports.getUsageCostUsd = getUsageCostUsd;
+exports.toSummary = toSummary;
+function safeClone(value) {
+    if (value === undefined) {
+        return value;
+    }
+    try {
+        const clone = globalThis.structuredClone;
+        if (typeof clone === 'function') {
+            return clone(value);
+        }
+    }
+    catch (_err) {
+        // fall through
+    }
+    try {
+        return JSON.parse(JSON.stringify(value));
+    }
+    catch (_err) {
+        return value;
+    }
+}
+function toErrorPayload(error) {
+    if (!error) {
+        return null;
+    }
+    const payload = {
+        message: error.message,
+        name: error.name,
+    };
+    for (const key of ['code', 'param', 'status', 'statusCode', 'type']) {
+        if (error[key] !== undefined) {
+            payload[key] = error[key];
+        }
+    }
+    if (error.stack) {
+        payload.stack = error.stack;
+    }
+    return payload;
+}
+function sanitizeHeaders(headers) {
+    if (!headers || typeof headers !== 'object') {
+        return {};
+    }
+    const sanitized = {};
+    for (const [key, value] of Object.entries(headers)) {
+        sanitized[key] = isSensitiveHeader(key) ? '[REDACTED]' : value;
+    }
+    return sanitized;
+}
+function isSensitiveHeader(key) {
+    return ['authorization', 'api-key', 'x-api-key', 'openai-api-key'].includes(String(key).toLowerCase());
+}
+function envFlag(name) {
+    const value = process.env[name];
+    if (!value) {
+        return false;
+    }
+    return !['0', 'false', 'off', 'no'].includes(String(value).toLowerCase());
+}
+function stringifyRecord(record) {
+    return Object.entries(record).reduce((acc, [key, value]) => {
+        if (value !== undefined && value !== null && value !== '') {
+            acc[key] = String(value);
+        }
+        return acc;
+    }, {});
+}
+function normalizeKind(value) {
+    if (!value) {
+        return null;
+    }
+    switch (value) {
+        case 'agent':
+            return 'actor';
+        case 'delegated-agent':
+            return 'child-actor';
+        case 'workflow-state':
+            return 'stage';
+        case 'watchdog':
+            return 'guardrail';
+        default:
+            return value;
+    }
+}
+function deriveGuardrailPhase(value) {
+    if (!value) {
+        return null;
+    }
+    const normalized = String(value).toLowerCase();
+    if (normalized.startsWith('input')) {
+        return 'input';
+    }
+    if (normalized.startsWith('output')) {
+        return 'output';
+    }
+    return null;
+}
+function normalizeTraceContext(context, mode) {
+    const raw = context || {};
+    const sessionId = raw.sessionId || raw.chatId || raw.rootSessionId || raw.rootChatId || null;
+    const rootSessionId = raw.rootSessionId || raw.rootChatId || sessionId || null;
+    const rootActorId = raw.rootActorId || raw.topLevelAgentId || raw.actorId || raw.agentId || null;
+    const actorId = raw.actorId || raw.agentId || rootActorId || null;
+    const actorType = raw.actorType || raw.contextType || null;
+    const stage = raw.stage || raw.workflowState || null;
+    const guardrailType = raw.guardrailType || raw.systemType || null;
+    const guardrailPhase = raw.guardrailPhase || raw.watchdogPhase || deriveGuardrailPhase(guardrailType);
+    const isChildActor = !!(actorId && rootActorId && actorId !== rootActorId);
+    const explicitKind = normalizeKind(raw.kind);
+    let kind = explicitKind || 'actor';
+    if (!explicitKind) {
+        if (guardrailType || guardrailPhase) {
+            kind = 'guardrail';
+        }
+        else if (stage) {
+            kind = 'stage';
+        }
+        else if (isChildActor) {
+            kind = 'child-actor';
+        }
+    }
+    const provider = raw.provider || null;
+    const model = raw.model || null;
+    const tags = stringifyRecord({
+        ...(raw.tags || {}),
+        actorId,
+        actorType,
+        guardrailPhase,
+        guardrailType,
+        kind,
+        mode,
+        model,
+        parentSessionId: raw.parentSessionId || raw.parentChatId || null,
+        provider,
+        rootActorId,
+        rootSessionId,
+        sessionId,
+        stage,
+        tenantId: raw.tenantId || null,
+        userId: raw.userId || null,
+        agentId: actorId,
+        chatId: sessionId,
+        contextType: actorType,
+        parentChatId: raw.parentSessionId || raw.parentChatId || null,
+        rootChatId: rootSessionId,
+        systemType: guardrailType,
+        topLevelAgentId: rootActorId,
+        watchdogPhase: guardrailPhase,
+        workflowState: stage,
+    });
+    return {
+        actorId,
+        actorType,
+        guardrailPhase,
+        guardrailType,
+        kind,
+        model,
+        parentSessionId: raw.parentSessionId || raw.parentChatId || null,
+        provider,
+        rootActorId,
+        rootSessionId,
+        sessionId,
+        stage,
+        tags,
+        tenantId: raw.tenantId || null,
+        userId: raw.userId || null,
+        agentId: actorId,
+        chatId: sessionId,
+        contextType: actorType,
+        parentChatId: raw.parentSessionId || raw.parentChatId || null,
+        rootChatId: rootSessionId,
+        systemType: guardrailType,
+        topLevelAgentId: rootActorId,
+        watchdogPhase: guardrailPhase,
+        workflowState: stage,
+        hierarchy: {
+            childActorId: isChildActor ? actorId : null,
+            guardrailPhase,
+            guardrailType,
+            kind,
+            rootActorId: rootActorId || 'unknown-actor',
+            sessionId: rootSessionId || sessionId || 'unknown-session',
+            stage,
+            chatId: rootSessionId || sessionId || 'unknown-session',
+            delegatedAgentId: isChildActor ? actorId : null,
+            systemType: guardrailType,
+            topLevelAgentId: rootActorId || 'unknown-actor',
+            watchdogPhase: guardrailPhase,
+            workflowState: stage,
+        },
+    };
+}
+function summariseValue(value, maxLength = 160) {
+    if (value === null || value === undefined) {
+        return '';
+    }
+    const text = typeof value === 'string' ? value : JSON.stringify(value);
+    if (text.length <= maxLength) {
+        return text;
+    }
+    return `${text.slice(0, maxLength - 1)}...`;
+}
+function getUsageCostUsd(usage) {
+    const promptTokens = toFiniteNumber(usage?.tokens?.prompt);
+    const completionTokens = toFiniteNumber(usage?.tokens?.completion);
+    const promptPricing = toFiniteNumber(usage?.pricing?.prompt);
+    const completionPricing = toFiniteNumber(usage?.pricing?.completion);
+    if (promptTokens === null || completionTokens === null || promptPricing === null || completionPricing === null) {
+        return null;
+    }
+    return roundCostUsd(promptTokens * promptPricing + completionTokens * completionPricing);
+}
+function toFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+function roundCostUsd(value) {
+    return Math.round(value * 1e12) / 1e12;
+}
+function extractRequestPreview(request) {
+    const messages = request?.input?.messages;
+    if (!Array.isArray(messages) || messages.length === 0) {
+        return '';
+    }
+    const lastUserMessage = [...messages].reverse().find((message) => message?.role === 'user');
+    if (!lastUserMessage) {
+        return summariseValue(messages[messages.length - 1]?.content);
+    }
+    return summariseValue(lastUserMessage.content);
+}
+function extractResponsePreview(trace) {
+    if (trace.mode === 'stream') {
+        const content = trace.stream?.reconstructed?.message?.content;
+        if (content) {
+            return summariseValue(content);
+        }
+    }
+    const content = trace.response?.message?.content;
+    if (content) {
+        return summariseValue(content);
+    }
+    if (trace.error?.message) {
+        return trace.error.message;
+    }
+    return '';
+}
+function toSummary(trace) {
+    const durationMs = trace.endedAt ? Math.max(0, Date.parse(trace.endedAt) - Date.parse(trace.startedAt)) : null;
+    return {
+        costUsd: getUsageCostUsd(trace.usage),
+        durationMs,
+        endedAt: trace.endedAt,
+        hierarchy: safeClone(trace.hierarchy),
+        id: trace.id,
+        kind: trace.kind,
+        mode: trace.mode,
+        model: trace.model,
+        provider: trace.provider,
+        requestPreview: extractRequestPreview(trace.request),
+        responsePreview: extractResponsePreview(trace),
+        startedAt: trace.startedAt,
+        status: trace.status,
+        stream: trace.stream
+            ? {
+                chunkCount: trace.stream.chunkCount,
+                firstChunkMs: trace.stream.firstChunkMs,
+            }
+            : null,
+        tags: safeClone(trace.tags),
+    };
+}

package/package.json ADDED Viewed

@@ -0,0 +1,71 @@
+{
+  "name": "@mtharrison/loupe",
+  "version": "1.0.0",
+  "description": "Lightweight local tracing dashboard for LLM calls",
+  "author": "Matt Harrison",
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "assets",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/build-ui.mjs",
+    "release": "npx semantic-release",
+    "test": "npm run build && node --test"
+  },
+  "release": {
+    "branches": [
+      "main"
+    ],
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      "@semantic-release/npm",
+      "@semantic-release/github"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "^5.9.2"
+  },
+  "keywords": [
+    "llm",
+    "observability",
+    "openai",
+    "tracing",
+    "trace",
+    "dashboard",
+    "local-dev"
+  ],
+  "dependencies": {
+    "clsx": "^2.1.1",
+    "esbuild": "^0.27.4",
+    "lucide-react": "^0.577.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1"
+  }
+}