coaiajs 0.1.0

package/dist/src/langfuse/scores.js

@@ -0,0 +1,366 @@
+// coaiajs/src/langfuse/scores.ts — Score operations
+// Port of cofuse.py score functions including configs, presets, import/export
+import { readFileSync, writeFileSync } from 'node:fs';
+import { getClient, nowISO } from './client.js';
+// ─── Score CRUD ─────────────────────────────────────────────────────
+export async function createScore(params) {
+    const client = getClient();
+    const data = { value: params.value };
+    if (params.id)
+        data.id = params.id;
+    if (params.name)
+        data.name = params.name;
+    if (params.traceId)
+        data.traceId = params.traceId;
+    if (params.observationId)
+        data.observationId = params.observationId;
+    if (params.configId)
+        data.configId = params.configId;
+    if (params.comment)
+        data.comment = params.comment;
+    const result = await client.request('POST', '/api/public/scores', data);
+    return JSON.stringify(result, null, 2);
+}
+export async function applyScoreToTrace(traceId, scoreId, value) {
+    return createScoreForTarget({
+        targetType: 'trace',
+        targetId: traceId,
+        scoreId,
+        value,
+    });
+}
+export async function createScoreForTarget(params) {
+    const client = getClient();
+    const data = { value: params.value };
+    if (params.targetType === 'trace') {
+        data.traceId = params.targetId;
+        if (params.observationId)
+            data.observationId = params.observationId;
+    }
+    else {
+        data.sessionId = params.targetId;
+    }
+    if (params.configId) {
+        data.configId = params.configId;
+    }
+    else {
+        if (params.scoreId)
+            data.id = params.scoreId;
+        if (params.scoreName)
+            data.name = params.scoreName;
+    }
+    if (params.comment)
+        data.comment = params.comment;
+    const result = await client.request('POST', '/api/public/scores', data);
+    return JSON.stringify(result, null, 2);
+}
+export async function listScores(filters) {
+    const client = getClient();
+    const allScores = [];
+    let page = filters.page ?? 1;
+    while (true) {
+        const params = new URLSearchParams({ page: String(page) });
+        if (filters.userId)
+            params.set('userId', filters.userId);
+        if (filters.name)
+            params.set('name', filters.name);
+        if (filters.fromTimestamp)
+            params.set('fromTimestamp', filters.fromTimestamp);
+        if (filters.toTimestamp)
+            params.set('toTimestamp', filters.toTimestamp);
+        if (filters.configId)
+            params.set('configId', filters.configId);
+        const data = await client.request('GET', `/api/public/v2/scores?${params.toString()}`);
+        const scores = data.data;
+        if (!scores || !Array.isArray(scores) || scores.length === 0)
+            break;
+        allScores.push(...scores);
+        if (!shouldContinuePagination(data, page))
+            break;
+        page++;
+    }
+    return JSON.stringify(allScores, null, 2);
+}
+// ─── Score Configs ──────────────────────────────────────────────────
+export async function listScoreConfigs() {
+    const client = getClient();
+    const allConfigs = [];
+    let page = 1;
+    while (true) {
+        const data = await client.request('GET', `/api/public/score-configs?page=${page}`);
+        const configs = data.data;
+        if (!configs || !Array.isArray(configs) || configs.length === 0)
+            break;
+        allConfigs.push(...configs);
+        if (!shouldContinuePagination(data, page))
+            break;
+        page++;
+    }
+    return JSON.stringify(allConfigs, null, 2);
+}
+export async function getScoreConfig(configId) {
+    const client = getClient();
+    const result = await client.request('GET', `/api/public/score-configs/${configId}`);
+    return JSON.stringify(result, null, 2);
+}
+export async function createScoreConfig(params) {
+    const client = getClient();
+    const data = {
+        name: params.name,
+        dataType: params.dataType,
+    };
+    if (params.description)
+        data.description = params.description;
+    if (params.categories)
+        data.categories = params.categories;
+    if (params.minValue !== undefined)
+        data.minValue = params.minValue;
+    if (params.maxValue !== undefined)
+        data.maxValue = params.maxValue;
+    const result = await client.request('POST', '/api/public/score-configs', data);
+    return JSON.stringify(result, null, 2);
+}
+export async function exportScoreConfigs(outputFile) {
+    const configsRaw = await listScoreConfigs();
+    const configs = JSON.parse(configsRaw);
+    const exported = configs.map((c) => ({
+        name: c.name,
+        dataType: c.dataType,
+        description: c.description,
+        categories: c.categories,
+        minValue: c.minValue,
+        maxValue: c.maxValue,
+        metadata: {
+            id: c.id,
+            createdAt: c.createdAt,
+            updatedAt: c.updatedAt,
+            projectId: c.projectId,
+            isArchived: c.isArchived,
+        },
+    }));
+    const exportData = {
+        version: '1.0',
+        exportedAt: nowISO(),
+        totalConfigs: exported.length,
+        configs: exported,
+    };
+    const json = JSON.stringify(exportData, null, 2);
+    if (outputFile) {
+        writeFileSync(outputFile, json, 'utf-8');
+    }
+    return json;
+}
+export async function importScoreConfigs(importFile, options) {
+    let importData;
+    try {
+        importData = JSON.parse(readFileSync(importFile, 'utf-8'));
+    }
+    catch (e) {
+        return `❌ Failed to read import file: ${e}`;
+    }
+    const configsList = Array.isArray(importData)
+        ? importData
+        : importData.configs ?? [];
+    if (!configsList.length)
+        return '❌ No score configs found in import file.';
+    const existingRaw = await listScoreConfigs();
+    const existing = JSON.parse(existingRaw);
+    const existingNames = new Set(existing.map((c) => String(c.name).toLowerCase()));
+    const selected = options?.selectedConfigs
+        ? new Set(options.selectedConfigs.map((n) => n.toLowerCase()))
+        : null;
+    const results = [];
+    let imported = 0;
+    let skipped = 0;
+    for (const raw of configsList) {
+        const cfg = raw;
+        const name = String(cfg.name);
+        if (selected && !selected.has(name.toLowerCase()))
+            continue;
+        if (existingNames.has(name.toLowerCase()) && !options?.allowDuplicates) {
+            results.push(`   ⏭️ '${name}' — skipped (duplicate)`);
+            skipped++;
+            continue;
+        }
+        try {
+            const result = await createScoreConfig({
+                name,
+                dataType: cfg.dataType,
+                description: cfg.description,
+                categories: cfg.categories,
+                minValue: cfg.minValue,
+                maxValue: cfg.maxValue,
+            });
+            const parsed = JSON.parse(result);
+            results.push(`   ✅ '${name}' (ID: ${parsed.id ?? 'created'})`);
+            imported++;
+        }
+        catch (e) {
+            results.push(`   ❌ '${name}' — ${e}`);
+        }
+    }
+    return [
+        `📁 Import: ${importFile}`,
+        `📊 Summary: ${imported} imported, ${skipped} skipped`,
+        ...results,
+    ].join('\n');
+}
+// ─── Score Config Caching / Apply ───────────────────────────────────
+export async function applyScoreConfig(configNameOrId, targetType, targetId, value, observationId, comment) {
+    // Resolve config: try by ID first, then search by name
+    let configId;
+    try {
+        const configJson = await getScoreConfig(configNameOrId);
+        const config = JSON.parse(configJson);
+        if (config.id)
+            configId = config.id;
+    }
+    catch {
+        // Try listing and searching by name
+        const allJson = await listScoreConfigs();
+        const all = JSON.parse(allJson);
+        const match = all.find((c) => String(c.name).toLowerCase() === configNameOrId.toLowerCase());
+        if (match)
+            configId = String(match.id);
+    }
+    if (!configId) {
+        return JSON.stringify({ error: `Score config '${configNameOrId}' not found` });
+    }
+    return createScoreForTarget({
+        targetType: targetType,
+        targetId,
+        configId,
+        value,
+        observationId,
+        comment,
+    });
+}
+// ─── Presets ────────────────────────────────────────────────────────
+export function getBuiltInPresets() {
+    return BUILT_IN_PRESETS.map((p) => ({ ...p }));
+}
+export async function installPreset(name, checkDuplicates = true) {
+    const preset = BUILT_IN_PRESETS.find((p) => p.name.toLowerCase() === name.toLowerCase());
+    if (!preset) {
+        return JSON.stringify({ error: `Preset '${name}' not found` });
+    }
+    if (checkDuplicates) {
+        const existingRaw = await listScoreConfigs();
+        const existing = JSON.parse(existingRaw);
+        const dup = existing.find((c) => String(c.name).toLowerCase() === preset.name.toLowerCase());
+        if (dup) {
+            return JSON.stringify({
+                warning: `Score config '${preset.name}' already exists (ID: ${dup.id})`,
+                existingId: dup.id,
+            });
+        }
+    }
+    return createScoreConfig({
+        name: preset.name,
+        dataType: preset.dataType,
+        description: preset.description,
+        categories: preset.categories,
+        minValue: preset.minValue,
+        maxValue: preset.maxValue,
+    });
+}
+// ─── Formatters ─────────────────────────────────────────────────────
+export function formatScoresTable(json) {
+    try {
+        const raw = typeof json === 'string' ? JSON.parse(json) : json;
+        const scores = Array.isArray(raw)
+            ? raw
+            : raw.data ?? [];
+        if (!scores.length)
+            return 'No scores found.';
+        const headers = ['ID', 'Name', 'Value', 'Created', 'Trace ID'];
+        const rows = scores.map((s) => [
+            trunc(String(s.id ?? 'N/A'), 20),
+            trunc(String(s.name ?? 'N/A'), 20),
+            String(s.value ?? 'N/A'),
+            String(s.createdAt ?? 'N/A').slice(0, 16),
+            trunc(String(s.traceId ?? 'N/A'), 20),
+        ]);
+        return formatTable(headers, rows) + `\nTotal scores: ${scores.length}`;
+    }
+    catch (e) {
+        return `Error formatting scores: ${e}`;
+    }
+}
+export function formatScoreConfigsTable(json) {
+    try {
+        const raw = typeof json === 'string' ? JSON.parse(json) : json;
+        const configs = Array.isArray(raw)
+            ? raw
+            : raw.data ?? [];
+        if (!configs.length)
+            return 'No score configs found.';
+        const headers = ['ID', 'Name', 'Data Type', 'Description', 'Created'];
+        const rows = configs.map((c) => [
+            trunc(String(c.id ?? 'N/A'), 20),
+            trunc(String(c.name ?? 'N/A'), 20),
+            String(c.dataType ?? 'N/A'),
+            trunc(String(c.description ?? 'N/A'), 35),
+            String(c.createdAt ?? 'N/A').slice(0, 16),
+        ]);
+        return formatTable(headers, rows) + `\nTotal score configs: ${configs.length}`;
+    }
+    catch (e) {
+        return `Error formatting score configs: ${e}`;
+    }
+}
+// ─── Built-in Presets ───────────────────────────────────────────────
+const BUILT_IN_PRESETS = [
+    // Narrative & Storytelling
+    { name: 'Narrative Coherence', dataType: 'CATEGORICAL', description: 'Evaluates how well story elements connect and flow together logically.', categories: [{ label: 'Incoherent', value: 1 }, { label: 'Loosely Connected', value: 2 }, { label: 'Coherent', value: 3 }, { label: 'Well-Structured', value: 4 }, { label: 'Masterfully Woven', value: 5 }] },
+    { name: 'Character Development', dataType: 'CATEGORICAL', description: 'Measures the depth and growth of characters throughout the narrative.', categories: [{ label: 'Flat/Static', value: 1 }, { label: 'Basic Development', value: 2 }, { label: 'Moderate Growth', value: 3 }, { label: 'Rich Development', value: 4 }, { label: 'Complex Evolution', value: 5 }] },
+    { name: 'Emotional Resonance', dataType: 'CATEGORICAL', description: 'Evaluates the emotional impact and connection with the audience.', categories: [{ label: 'No Emotional Impact', value: 1 }, { label: 'Mild Resonance', value: 2 }, { label: 'Moderate Impact', value: 3 }, { label: 'Strong Emotional Connection', value: 4 }, { label: 'Deeply Moving', value: 5 }] },
+    { name: 'Originality', dataType: 'CATEGORICAL', description: 'Evaluates the uniqueness and freshness of the ideas or expression.', categories: [{ label: 'Unoriginal', value: 1 }, { label: 'Low Originality', value: 2 }, { label: 'Moderate Originality', value: 3 }, { label: 'High Originality', value: 4 }, { label: 'Highly Original', value: 5 }] },
+    { name: 'Thematic Depth', dataType: 'CATEGORICAL', description: 'Measures the depth and sophistication of underlying themes.', categories: [{ label: 'Surface Level', value: 1 }, { label: 'Basic Themes', value: 2 }, { label: 'Developed Themes', value: 3 }, { label: 'Rich Thematic Content', value: 4 }, { label: 'Profound Depth', value: 5 }] },
+    // AI Response Evaluation
+    { name: 'Helpfulness', dataType: 'CATEGORICAL', description: 'Measures how well the response addresses the user\'s needs.', categories: [{ label: 'Not Helpful', value: 1 }, { label: 'Slightly Helpful', value: 2 }, { label: 'Moderately Helpful', value: 3 }, { label: 'Very Helpful', value: 4 }, { label: 'Extremely Helpful', value: 5 }] },
+    { name: 'Accuracy', dataType: 'CATEGORICAL', description: 'Evaluates the factual correctness and precision of information.', categories: [{ label: 'Inaccurate', value: 1 }, { label: 'Mostly Inaccurate', value: 2 }, { label: 'Partially Accurate', value: 3 }, { label: 'Mostly Accurate', value: 4 }, { label: 'Completely Accurate', value: 5 }] },
+    { name: 'Safety', dataType: 'CATEGORICAL', description: 'Assesses whether the content is safe and free from harmful elements.', categories: [{ label: 'Unsafe/Harmful', value: 1 }, { label: 'Potentially Unsafe', value: 2 }, { label: 'Neutral/Safe', value: 3 }, { label: 'Very Safe', value: 4 }, { label: 'Exemplarily Safe', value: 5 }] },
+    { name: 'Relevance', dataType: 'CATEGORICAL', description: 'Measures how well the response relates to the specific query.', categories: [{ label: 'Irrelevant', value: 1 }, { label: 'Slightly Relevant', value: 2 }, { label: 'Moderately Relevant', value: 3 }, { label: 'Highly Relevant', value: 4 }, { label: 'Perfectly Relevant', value: 5 }] },
+    { name: 'Completeness', dataType: 'CATEGORICAL', description: 'Evaluates whether the response fully addresses all aspects.', categories: [{ label: 'Incomplete', value: 1 }, { label: 'Partially Complete', value: 2 }, { label: 'Mostly Complete', value: 3 }, { label: 'Very Complete', value: 4 }, { label: 'Comprehensive', value: 5 }] },
+    // General Content
+    { name: 'Clarity', dataType: 'CATEGORICAL', description: 'Measures how easy it is to understand the content.', categories: [{ label: 'Unclear', value: 1 }, { label: 'Moderately Clear', value: 2 }, { label: 'Clear', value: 3 }, { label: 'Very Clear', value: 4 }, { label: 'Excellent Clarity', value: 5 }] },
+    { name: 'Engagement', dataType: 'CATEGORICAL', description: 'Evaluates how well the content captures attention.', categories: [{ label: 'Disengaging', value: 1 }, { label: 'Slightly Engaging', value: 2 }, { label: 'Engaging', value: 3 }, { label: 'Very Engaging', value: 4 }, { label: 'Highly Engaging', value: 5 }] },
+    { name: 'Tone Appropriateness', dataType: 'CATEGORICAL', description: 'Assesses whether the tone matches context and audience expectations.', categories: [{ label: 'Inappropriate Tone', value: 1 }, { label: 'Somewhat Inappropriate', value: 2 }, { label: 'Acceptable Tone', value: 3 }, { label: 'Well-Matched Tone', value: 4 }, { label: 'Perfect Tone', value: 5 }] },
+    { name: 'Conciseness', dataType: 'CATEGORICAL', description: 'Evaluates the efficiency of communication.', categories: [{ label: 'Verbose/Wordy', value: 1 }, { label: 'Somewhat Verbose', value: 2 }, { label: 'Balanced', value: 3 }, { label: 'Concise', value: 4 }, { label: 'Perfectly Concise', value: 5 }] },
+    // Technical Quality
+    { name: 'Structure & Organization', dataType: 'CATEGORICAL', description: 'Evaluates the logical organization and structural quality.', categories: [{ label: 'Disorganized', value: 1 }, { label: 'Basic Structure', value: 2 }, { label: 'Well-Organized', value: 3 }, { label: 'Excellent Structure', value: 4 }, { label: 'Masterful Organization', value: 5 }] },
+    { name: 'Language Quality', dataType: 'CATEGORICAL', description: 'Assesses grammar, vocabulary usage, and linguistic competence.', categories: [{ label: 'Poor Language', value: 1 }, { label: 'Fair Language', value: 2 }, { label: 'Good Language', value: 3 }, { label: 'Excellent Language', value: 4 }, { label: 'Exceptional Language', value: 5 }] },
+    // Specialized
+    { name: 'Critical Thinking', dataType: 'CATEGORICAL', description: 'Measures the depth of analysis, reasoning, and intellectual rigor.', categories: [{ label: 'No Critical Analysis', value: 1 }, { label: 'Basic Analysis', value: 2 }, { label: 'Sound Reasoning', value: 3 }, { label: 'Strong Critical Thinking', value: 4 }, { label: 'Exceptional Analysis', value: 5 }] },
+    { name: 'Evidence Support', dataType: 'CATEGORICAL', description: 'Evaluates the use and quality of supporting evidence.', categories: [{ label: 'No Evidence', value: 1 }, { label: 'Weak Evidence', value: 2 }, { label: 'Adequate Evidence', value: 3 }, { label: 'Strong Evidence', value: 4 }, { label: 'Compelling Evidence', value: 5 }] },
+    { name: 'Innovation', dataType: 'CATEGORICAL', description: 'Assesses creativity and novel approaches in problem-solving.', categories: [{ label: 'Conventional', value: 1 }, { label: 'Slightly Creative', value: 2 }, { label: 'Moderately Innovative', value: 3 }, { label: 'Highly Innovative', value: 4 }, { label: 'Groundbreaking', value: 5 }] },
+    // Numeric
+    { name: 'Overall Quality', dataType: 'NUMERIC', description: 'General numeric assessment of overall content quality.', minValue: 0, maxValue: 10 },
+    { name: 'Performance Score', dataType: 'NUMERIC', description: 'Numeric performance evaluation score.', minValue: 0, maxValue: 100 },
+    // Boolean
+    { name: 'Meets Requirements', dataType: 'BOOLEAN', description: 'Binary assessment of whether content meets specified requirements.' },
+];
+// ─── Helpers ────────────────────────────────────────────────────────
+function shouldContinuePagination(data, currentPage) {
+    const meta = data.meta;
+    if (meta?.totalPages) {
+        return (meta.page ?? currentPage) < meta.totalPages;
+    }
+    if (data.hasNextPage)
+        return true;
+    if (data.totalPages && currentPage < data.totalPages)
+        return true;
+    return false;
+}
+function trunc(s, len) {
+    return s.length > len ? s.slice(0, len - 3) + '...' : s;
+}
+function formatTable(headers, rows) {
+    const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? '').length)));
+    const sep = '+' + widths.map((w) => '-'.repeat(w + 2)).join('+') + '+';
+    const hdr = '| ' + headers.map((h, i) => h.padEnd(widths[i])).join(' | ') + ' |';
+    const body = rows.map((r) => '| ' + r.map((c, i) => (c ?? '').padEnd(widths[i])).join(' | ') + ' |');
+    return [sep, hdr, sep, ...body, sep].join('\n');
+}
+//# sourceMappingURL=scores.js.map

package/dist/src/langfuse/traces.d.ts

@@ -0,0 +1,29 @@
+export interface TraceFilters {
+    sessionId?: string;
+    userId?: string;
+    name?: string;
+    tags?: string[];
+    fromTimestamp?: string;
+    toTimestamp?: string;
+    orderBy?: string;
+    version?: string;
+    release?: string;
+    environment?: string[];
+    page?: number;
+    limit?: number;
+}
+export declare function addTrace(params: {
+    traceId?: string;
+    userId?: string;
+    sessionId?: string;
+    name?: string;
+    inputData?: unknown;
+    outputData?: unknown;
+    metadata?: unknown;
+}): Promise<string>;
+export declare function patchTraceOutput(traceId: string, outputData: unknown): Promise<string>;
+export declare function listTraces(filters: TraceFilters): Promise<string>;
+export declare function getTrace(traceId: string): Promise<string>;
+export declare function formatTracesTable(json: unknown): string;
+export declare function formatTraceTree(json: unknown): string;
+//# sourceMappingURL=traces.d.ts.map

package/dist/src/langfuse/traces.js

@@ -0,0 +1,225 @@
+// coaiajs/src/langfuse/traces.ts — Trace operations
+// Port of cofuse.py trace functions
+import { v4 as uuidv4 } from 'uuid';
+import { getClient, nowISO } from './client.js';
+export async function addTrace(params) {
+    const client = getClient();
+    const now = nowISO();
+    const traceId = params.traceId ?? uuidv4();
+    const body = {
+        id: traceId,
+        timestamp: now,
+    };
+    if (params.sessionId)
+        body.sessionId = params.sessionId;
+    if (params.name)
+        body.name = params.name;
+    if (params.inputData)
+        body.input = params.inputData;
+    if (params.outputData)
+        body.output = params.outputData;
+    if (params.userId)
+        body.userId = params.userId;
+    if (params.metadata)
+        body.metadata = params.metadata;
+    const event = {
+        id: `${traceId}-event`,
+        timestamp: now,
+        type: 'trace-create',
+        body,
+    };
+    await client.ingest([event]);
+    return JSON.stringify({
+        success: true,
+        traceId,
+        message: `Trace ${traceId} created`,
+    }, null, 2);
+}
+export async function patchTraceOutput(traceId, outputData) {
+    const client = getClient();
+    const now = nowISO();
+    const body = {
+        id: traceId,
+        timestamp: now,
+        output: outputData,
+    };
+    const eventId = `${traceId}-patch-${uuidv4().slice(0, 8)}`;
+    const event = {
+        id: eventId,
+        timestamp: now,
+        type: 'trace-create',
+        body,
+    };
+    await client.ingest([event]);
+    return JSON.stringify({
+        success: true,
+        traceId,
+        message: `Trace output patched for ${traceId}`,
+    }, null, 2);
+}
+export async function listTraces(filters) {
+    const client = getClient();
+    const params = new URLSearchParams();
+    if (filters.sessionId)
+        params.set('sessionId', filters.sessionId);
+    if (filters.userId)
+        params.set('userId', filters.userId);
+    if (filters.name)
+        params.set('name', filters.name);
+    if (filters.fromTimestamp)
+        params.set('fromTimestamp', filters.fromTimestamp);
+    if (filters.toTimestamp)
+        params.set('toTimestamp', filters.toTimestamp);
+    if (filters.orderBy)
+        params.set('orderBy', filters.orderBy);
+    if (filters.version)
+        params.set('version', filters.version);
+    if (filters.release)
+        params.set('release', filters.release);
+    if (filters.tags) {
+        for (const tag of filters.tags)
+            params.append('tags', tag);
+    }
+    if (filters.environment) {
+        for (const env of filters.environment)
+            params.append('environment', env);
+    }
+    const page = filters.page ?? 1;
+    const limit = filters.limit ?? 50;
+    params.set('page', String(page));
+    params.set('limit', String(limit));
+    const qs = params.toString();
+    const path = `/api/public/traces${qs ? `?${qs}` : ''}`;
+    const result = await client.request('GET', path);
+    return JSON.stringify(result, null, 2);
+}
+export async function getTrace(traceId) {
+    const client = getClient();
+    const trace = await client.request('GET', `/api/public/traces/${traceId}`);
+    // Fetch observations for this trace
+    try {
+        const obsResult = await client.request('GET', `/api/public/observations?traceId=${traceId}`);
+        if (obsResult && typeof obsResult === 'object' && 'data' in obsResult) {
+            trace.observations = obsResult.data;
+        }
+        else {
+            trace.observations = obsResult;
+        }
+    }
+    catch {
+        trace.observations = [];
+    }
+    return JSON.stringify(trace, null, 2);
+}
+// ─── Formatters ─────────────────────────────────────────────────────
+export function formatTracesTable(json) {
+    try {
+        const data = typeof json === 'string' ? JSON.parse(json) : json;
+        const traces = Array.isArray(data)
+            ? data
+            : data.data ?? [];
+        if (!traces.length)
+            return 'No traces found.';
+        const headers = ['ID', 'Name', 'Session', 'User', 'Time'];
+        const rows = traces.map((t) => [
+            trunc(String(t.id ?? 'N/A'), 20),
+            trunc(String(t.name ?? 'Unnamed'), 20),
+            trunc(String(t.sessionId ?? 'N/A'), 15),
+            trunc(String(t.userId ?? 'N/A'), 12),
+            trunc(String(t.timestamp ?? 'N/A').slice(0, 19), 19),
+        ]);
+        return formatTable(headers, rows) + `\nTotal traces: ${traces.length}`;
+    }
+    catch (e) {
+        return `Error formatting traces: ${e}`;
+    }
+}
+const TYPE_GLYPHS = {
+    SPAN: '🔗',
+    GENERATION: '🤖',
+    EVENT: '⚡',
+    SCORE: '📊',
+    TRACE: '🛤️',
+    DEFAULT: '📦',
+};
+export function formatTraceTree(json) {
+    try {
+        const trace = (typeof json === 'string' ? JSON.parse(json) : json);
+        if ('error' in trace)
+            return `Error: ${trace.error}`;
+        const BRANCH = '├── ';
+        const LAST = '└── ';
+        const VERT = '│   ';
+        const SPACE = '    ';
+        const lines = [];
+        const name = String(trace.name ?? 'Unnamed');
+        const id = String(trace.id ?? 'N/A');
+        const userId = String(trace.userId ?? 'N/A');
+        const sessionId = String(trace.sessionId ?? 'N/A');
+        const ts = String(trace.timestamp ?? 'N/A').slice(0, 19);
+        lines.push(`🔗 Trace: ${name}`);
+        lines.push(`${BRANCH}🆔 ID: ${id}`);
+        lines.push(`${BRANCH}👤 User: ${userId}`);
+        lines.push(`${BRANCH}🔗 Session: ${sessionId}`);
+        lines.push(`${BRANCH}⏰ Time: ${ts}`);
+        const metadata = trace.metadata;
+        if (metadata && typeof metadata === 'object' && Object.keys(metadata).length) {
+            lines.push(`${BRANCH}📋 Metadata:`);
+            const entries = Object.entries(metadata);
+            entries.forEach(([k, v], i) => {
+                const pre = i === entries.length - 1 ? LAST : BRANCH;
+                lines.push(`${VERT}${pre}${k}: ${v}`);
+            });
+        }
+        const observations = (trace.observations ?? []);
+        if (!observations.length) {
+            lines.push(`${LAST}📝 No observations`);
+            return lines.join('\n');
+        }
+        lines.push(`${LAST}📝 Observations (${observations.length}):`);
+        const roots = observations.filter((o) => !o.parentObservationId);
+        function addTree(list, prefix) {
+            list.forEach((obs, i) => {
+                const isLast = i === list.length - 1;
+                const obsName = String(obs.name ?? `Obs ${String(obs.id ?? '').slice(0, 8)}`);
+                const obsType = String(obs.type ?? 'UNKNOWN').toUpperCase();
+                const obsTime = String(obs.startTime ?? 'N/A').slice(0, 19);
+                const glyph = TYPE_GLYPHS[obsType] ?? TYPE_GLYPHS.DEFAULT;
+                const sym = isLast ? LAST : BRANCH;
+                const np = prefix + (isLast ? SPACE : VERT);
+                lines.push(`${prefix}${sym}${glyph} [${obsType}] ${obsName} (${obs.id})`);
+                lines.push(`${np}${BRANCH}⏰ ${obsTime}`);
+                if (obs.input) {
+                    const txt = trunc(String(obs.input).replace(/\n/g, ' '), 90);
+                    lines.push(`${np}${BRANCH}📥 Input: ${txt}`);
+                }
+                if (obs.output) {
+                    const txt = trunc(String(obs.output).replace(/\n/g, ' '), 90);
+                    lines.push(`${np}${LAST}📤 Output: ${txt}`);
+                }
+                const children = observations.filter((c) => c.parentObservationId === obs.id);
+                if (children.length) {
+                    lines.push(`${np}${LAST}🌿 Children (${children.length}):`);
+                    addTree(children, np + SPACE);
+                }
+            });
+        }
+        addTree(roots, SPACE);
+        return lines.join('\n');
+    }
+    catch (e) {
+        return `Error formatting trace tree: ${e}`;
+    }
+}
+// ─── Helpers ────────────────────────────────────────────────────────
+function trunc(s, len) {
+    return s.length > len ? s.slice(0, len - 3) + '...' : s;
+}
+function formatTable(headers, rows) {
+    const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? '').length)));
+    const sep = '+' + widths.map((w) => '-'.repeat(w + 2)).join('+') + '+';
+    const hdr = '| ' + headers.map((h, i) => h.padEnd(widths[i])).join(' | ') + ' |';
+    const body = rows.map((r) => '| ' + r.map((c, i) => (c ?? '').padEnd(widths[i])).join(' | ') + ' |');
+    return [sep, hdr, sep, ...body, sep].join('\n');
+}
+//# sourceMappingURL=traces.js.map

package/dist/src/llm.d.ts

@@ -0,0 +1,23 @@
+/** Reset client (testing). */
+export declare function resetClient(): void;
+/**
+ * Send a chat completion request.
+ * Minimal wrapper matching coaiapy's `llm()` function.
+ */
+export declare function llm(user: string, system?: string, temperature?: number): Promise<string>;
+/**
+ * Transcribe audio using Whisper API.
+ * Parity with coaiapy's transcription functions.
+ */
+export declare function transcribeAudio(filePath: string): Promise<string>;
+/**
+ * Generate an image using DALL-E.
+ * Returns the URL of the generated image.
+ */
+export declare function generateImage(prompt: string, size?: string): Promise<string>;
+/**
+ * Abstract process: config-driven LLM call with a named process.
+ * Looks up system prompt by processName in config or uses a default.
+ */
+export declare function abstractProcess(processName: string, input: string): Promise<string>;
+//# sourceMappingURL=llm.d.ts.map