truthguard-ai 0.1.0

package/dist/Trace/index.js

@@ -0,0 +1,763 @@
+"use strict";
+/**
+ * Trace SDK
+ *
+ * Provides a fluent builder for constructing agent execution traces and
+ * utility helpers for querying them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TraceUtils = exports.TraceBuilder = void 0;
+const crypto_1 = require("crypto");
+/**
+ * Fluent builder for constructing a {@link Trace}.
+ *
+ * @example
+ * ```ts
+ * const trace = new TraceBuilder({ metadata: { sessionId: 'abc' } })
+ *   .addUserInput('How many employees are on leave today?')
+ *   .addToolCall('getLeaveRecords', { date: '2024-03-15' })
+ *   .addToolOutput('getLeaveRecords', [{ employeeId: 'E01', name: 'Ana' }, { employeeId: 'E02', name: 'Ivo' }])
+ *   .addFinalResponse('There are 2 employees on leave today.')
+ *   .build();
+ * ```
+ */
+class TraceBuilder {
+    constructor(options = {}) {
+        this.steps = [];
+        this.traceId = options.traceId ?? (0, crypto_1.randomUUID)();
+        this.metadata = options.metadata ?? {};
+        this.startedAt = new Date().toISOString();
+    }
+    /** Add a system prompt step (static context/instructions). */
+    addSystemPrompt(content, meta) {
+        return this.addStep('system_prompt', content, meta);
+    }
+    /** Add a user input step. */
+    addUserInput(content, meta) {
+        return this.addStep('user_input', content, meta);
+    }
+    /** Add a tool call step. */
+    addToolCall(toolName, parameters, meta) {
+        const toolCall = {
+            toolName,
+            parameters,
+            calledAt: new Date().toISOString(),
+        };
+        return this.addStep('tool_call', `Tool call: ${toolName}`, {
+            ...meta,
+            toolCalls: [...(meta?.toolCalls ?? []), toolCall],
+        });
+    }
+    /** Add a tool output step. */
+    addToolOutput(toolName, output, meta) {
+        const toolOutput = {
+            toolName,
+            output,
+            receivedAt: new Date().toISOString(),
+        };
+        return this.addStep('tool_output', `Tool output: ${toolName}`, {
+            ...meta,
+            toolOutputs: [...(meta?.toolOutputs ?? []), toolOutput],
+        });
+    }
+    /** Add an LLM call step (e.g., intermediate reasoning). */
+    addLlmCall(content, meta) {
+        return this.addStep('llm_call', content, meta);
+    }
+    /** Add the final response step. */
+    addFinalResponse(content, meta) {
+        return this.addStep('final_response', content, meta);
+    }
+    /** Low-level step addition. */
+    addStep(role, content, meta) {
+        const step = {
+            stepId: (0, crypto_1.randomUUID)(),
+            role,
+            content,
+            startedAt: new Date().toISOString(),
+            ...meta,
+        };
+        this.steps.push(step);
+        return this;
+    }
+    /** Build and return the completed {@link Trace}. */
+    build() {
+        const endedAt = new Date().toISOString();
+        const startMs = new Date(this.startedAt).getTime();
+        const endMs = new Date(endedAt).getTime();
+        return {
+            traceId: this.traceId,
+            steps: this.steps,
+            startedAt: this.startedAt,
+            endedAt,
+            totalLatencyMs: endMs - startMs,
+            metadata: this.metadata,
+        };
+    }
+}
+exports.TraceBuilder = TraceBuilder;
+// ---------------------------------------------------------------------------
+// Period inference helpers
+// ---------------------------------------------------------------------------
+const MONTH_NAMES = {
+    january: '01', jan: '01', februar: '02', february: '02', feb: '02',
+    mart: '03', march: '03', mar: '03', april: '04', apr: '04',
+    maj: '05', may: '05', jun: '06', june: '06', jul: '07', july: '07',
+    avgust: '08', august: '08', aug: '08', septembar: '09', september: '09', sep: '09',
+    oktobar: '10', october: '10', oct: '10', novembar: '11', november: '11', nov: '11',
+    decembar: '12', december: '12', dec: '12',
+    /* Serbian cyrillic-latin additional forms */
+    januar: '01',
+};
+/** Find a param value by trying multiple key names (case-insensitive). */
+function findParam(params, keys) {
+    for (const k of keys) {
+        const kLower = k.toLowerCase();
+        for (const [pk, pv] of Object.entries(params)) {
+            if (pk.toLowerCase() === kLower)
+                return pv;
+        }
+    }
+    return undefined;
+}
+/** Find a date-like param and normalise to ISO date string. */
+function findDateParam(params, keys) {
+    const val = findParam(params, keys);
+    if (val === undefined || val === null)
+        return undefined;
+    const s = String(val).trim();
+    // Already ISO: "2024-03-15" or "2024-03"
+    if (/^\d{4}-\d{2}(-\d{2})?$/.test(s))
+        return s;
+    // European: "15.03.2024" → "2024-03-15"
+    const eu = s.match(/^(\d{1,2})\.(\d{1,2})\.(\d{4})\.?$/);
+    if (eu)
+        return `${eu[3]}-${eu[2].padStart(2, '0')}-${eu[1].padStart(2, '0')}`;
+    return s; // pass-through as-is
+}
+/** Normalise a month value like "2024-01", "January 2024", "januar 2024" → "2024-MM". */
+function normaliseMonth(raw) {
+    const trimmed = raw.trim();
+    // Already ISO month: "2024-01"
+    if (/^\d{4}-\d{2}$/.test(trimmed))
+        return trimmed;
+    // "January 2024" or "januar 2024"
+    const parts = trimmed.split(/\s+/);
+    if (parts.length === 2) {
+        const monthNum = MONTH_NAMES[parts[0].toLowerCase()];
+        const year = parts[1];
+        if (monthNum && /^\d{4}$/.test(year))
+            return `${year}-${monthNum}`;
+        // Reversed: "2024 January"
+        const monthNum2 = MONTH_NAMES[parts[1].toLowerCase()];
+        if (monthNum2 && /^\d{4}$/.test(parts[0]))
+            return `${parts[0]}-${monthNum2}`;
+    }
+    // "February 2024" with lowercase already handled
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Trace normalizer helpers — detect and convert external formats
+// ---------------------------------------------------------------------------
+/** Safely attempt to parse a string as JSON; returns the original string on failure. */
+function tryParseJSON(s) {
+    if (!s || typeof s !== 'string')
+        return s;
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return s;
+    }
+}
+/** OpenAI format: assistant message may carry a `tool_calls` array. */
+function hasToolCallsPayload(raw) {
+    const tc = raw['tool_calls'] ?? raw['toolCalls'];
+    return Array.isArray(tc) && tc.length > 0;
+}
+/** Extract ToolCall[] from an OpenAI-format assistant step. */
+function extractOpenAIToolCalls(raw) {
+    const arr = (raw['tool_calls'] ?? raw['toolCalls']);
+    if (!Array.isArray(arr))
+        return [];
+    return arr.map((tc) => {
+        const fn = (tc['function'] ?? tc);
+        let params = {};
+        const args = fn['arguments'] ?? fn['parameters'] ?? tc['parameters'];
+        if (typeof args === 'string') {
+            try {
+                params = JSON.parse(args);
+            }
+            catch {
+                params = { _raw: args };
+            }
+        }
+        else if (args && typeof args === 'object') {
+            params = args;
+        }
+        return {
+            toolName: (fn['name'] ?? tc['name'] ?? tc['toolName'] ?? 'unknown'),
+            parameters: params,
+        };
+    });
+}
+/** Anthropic format: assistant message has content blocks with type='tool_use'. */
+function hasAnthropicToolUse(raw) {
+    const content = raw['content'];
+    return Array.isArray(content) && content.some((b) => b?.type === 'tool_use');
+}
+/** Extract ToolCall[] from an Anthropic-format assistant step. */
+function extractAnthropicToolCalls(raw) {
+    const content = raw['content'];
+    if (!Array.isArray(content))
+        return [];
+    return content
+        .filter((b) => b?.type === 'tool_use')
+        .map((b) => ({
+        toolName: (b['name'] ?? 'unknown'),
+        parameters: (b['input'] ?? {}),
+    }));
+}
+/** Anthropic format: user message has content blocks with type='tool_result'. */
+function hasAnthropicToolResult(raw) {
+    const content = raw['content'];
+    return Array.isArray(content) && content.some((b) => b?.type === 'tool_result');
+}
+/** Extract ToolOutput[] from an Anthropic-format tool_result step. */
+function extractAnthropicToolResults(raw) {
+    const content = raw['content'];
+    if (!Array.isArray(content))
+        return [];
+    return content
+        .filter((b) => b?.type === 'tool_result')
+        .map((b) => {
+        let output = b['content'];
+        if (typeof output === 'string')
+            output = tryParseJSON(output);
+        return {
+            toolName: (b['tool_use_id'] ?? b['name'] ?? 'unknown'),
+            output,
+        };
+    });
+}
+// ---------------------------------------------------------------------------
+// TraceUtils — query helpers
+// ---------------------------------------------------------------------------
+/** Utility helpers for querying a {@link Trace}. */
+exports.TraceUtils = {
+    /**
+     * Return all steps matching a given role.
+     */
+    getStepsByRole(trace, role) {
+        return (trace?.steps ?? []).filter((s) => s.role === role);
+    },
+    /**
+     * Return the final response step, or undefined if not present.
+     */
+    getFinalResponse(trace) {
+        const steps = exports.TraceUtils.getStepsByRole(trace, 'final_response');
+        return steps[steps.length - 1];
+    },
+    /**
+     * Return all tool outputs flattened from all tool_output steps.
+     */
+    getAllToolOutputs(trace) {
+        return (trace?.steps ?? [])
+            .filter((s) => s.role === 'tool_output' && s.toolOutputs)
+            .flatMap((s) => s.toolOutputs ?? []);
+    },
+    /**
+     * Return all tool calls flattened from all tool_call steps.
+     */
+    getAllToolCalls(trace) {
+        return (trace?.steps ?? [])
+            .filter((s) => s.role === 'tool_call' && s.toolCalls)
+            .flatMap((s) => s.toolCalls ?? []);
+    },
+    /**
+     * Return all tool output steps (with their stepId preserved).
+     */
+    getToolOutputSteps(trace) {
+        return (trace?.steps ?? []).filter((s) => s.role === 'tool_output');
+    },
+    /**
+     * Check whether any tool was called in this trace.
+     *
+     * Returns true if ANY of these conditions hold:
+     * 1. A step has role='tool_call', OR
+     * 2. A step has role='tool_output' (some proxies emit only outputs).
+     */
+    hasToolCalls(trace) {
+        return (trace?.steps ?? []).some((s) => s.role === 'tool_call' || s.role === 'tool_output');
+    },
+    /**
+     * Return the system prompt step, or undefined if not present.
+     */
+    getSystemPrompt(trace) {
+        const steps = exports.TraceUtils.getStepsByRole(trace, 'system_prompt');
+        return steps[0];
+    },
+    /**
+     * Serialise a trace to a JSON string.
+     */
+    toJSON(trace) {
+        return JSON.stringify(trace ?? {}, null, 2);
+    },
+    /**
+     * Deserialise a trace from a JSON string.
+     */
+    fromJSON(json) {
+        return JSON.parse(json);
+    },
+    // -----------------------------------------------------------------------
+    // Multi-turn conversation helpers
+    // -----------------------------------------------------------------------
+    /**
+     * Parse trace steps into an ordered list of conversation turns.
+     *
+     * Algorithm (generic, works for any agent framework):
+     * 1. Skip `system_prompt` / `llm_call` steps — they are not turn boundaries.
+     * 2. A new turn starts at a `user_input` that either:
+     *    - is the first `user_input` in the trace, or
+     *    - follows a `final_response` (i.e. a previous turn already ended).
+     * 3. Consecutive `user_input` steps with identical content are de-duped
+     *    (a common pattern when agents re-send the message).
+     * 4. Tool call / tool output steps are assigned to the current turn.
+     * 5. A `final_response` closes the current turn.
+     * 6. The last turn is marked `isActive`.
+     */
+    getConversationTurns(trace) {
+        const steps = trace?.steps ?? [];
+        const turns = [];
+        let current = null;
+        let lastRole = null;
+        for (const step of steps) {
+            if (step.role === 'system_prompt' || step.role === 'llm_call') {
+                continue;
+            }
+            if (step.role === 'user_input') {
+                // Dedup: skip consecutive user_input with identical content
+                if (current && lastRole === 'user_input' && current.userInput === step.content) {
+                    continue;
+                }
+                // New turn boundary: first input, or after a final_response
+                if (!current || lastRole === 'final_response') {
+                    current = {
+                        userInput: step.content,
+                        toolCalls: [],
+                        toolOutputs: [],
+                        response: '',
+                        isActive: false,
+                    };
+                    turns.push(current);
+                }
+                else if (current && lastRole === 'user_input') {
+                    // Different user_input following another user_input without a
+                    // final_response in between → replace (overwrite) the current
+                    // turn's question (the agent re-framed / the user re-phrased).
+                    current.userInput = step.content;
+                }
+                lastRole = 'user_input';
+                continue;
+            }
+            if (!current)
+                continue; // steps before first user_input — skip
+            if (step.role === 'tool_call') {
+                current.toolCalls.push(step);
+            }
+            else if (step.role === 'tool_output') {
+                current.toolOutputs.push(step);
+            }
+            else if (step.role === 'final_response') {
+                current.response = step.content;
+                lastRole = 'final_response';
+                continue;
+            }
+            lastRole = step.role;
+        }
+        // Mark the last turn as active
+        if (turns.length > 0) {
+            turns[turns.length - 1].isActive = true;
+        }
+        return turns;
+    },
+    /**
+     * Return the active (last) conversation turn, or `undefined` for
+     * single-step traces with no `user_input`.
+     */
+    getActiveTurn(trace) {
+        const turns = exports.TraceUtils.getConversationTurns(trace);
+        return turns.length > 0 ? turns[turns.length - 1] : undefined;
+    },
+    /**
+     * Return the user question from the active (last) turn only.
+     *
+     * For single-turn traces this returns the same as joining all
+     * `user_input` contents. For multi-turn traces it returns only
+     * the last question — the one being evaluated.
+     *
+     * When the trace was built by `buildActiveTurnTrace`, the original
+     * active question is stored in `metadata.activeUserInput` (the
+     * user_input step contains the full contextual history).
+     */
+    getActiveUserInput(trace) {
+        const fromMeta = trace.metadata?.activeUserInput;
+        if (typeof fromMeta === 'string' && fromMeta.length > 0)
+            return fromMeta;
+        return exports.TraceUtils.getActiveTurn(trace)?.userInput ?? '';
+    },
+    /**
+     * Return a context-enriched version of the active user input.
+     *
+     * If the trace has multiple turns, the earlier Q&A pairs are
+     * prepended so that rules can understand follow-up references
+     * like "what about the same for March?" or "po sektorima".
+     *
+     * Returns the plain active input for single-turn traces.
+     */
+    getContextualUserInput(trace) {
+        const turns = exports.TraceUtils.getConversationTurns(trace);
+        if (turns.length <= 1) {
+            return turns[0]?.userInput ?? '';
+        }
+        const historyParts = [];
+        for (let i = 0; i < turns.length - 1; i++) {
+            historyParts.push(`Q: ${turns[i].userInput}`);
+            if (turns[i].response) {
+                // Include only a short prefix of the response for context
+                const respPreview = turns[i].response.length > 200
+                    ? turns[i].response.slice(0, 200) + '…'
+                    : turns[i].response;
+                historyParts.push(`A: ${respPreview}`);
+            }
+        }
+        const active = turns[turns.length - 1];
+        return [...historyParts, `Q: ${active.userInput}`].join('\n');
+    },
+    /**
+     * Return tool outputs from only the active (last) conversation turn.
+     *
+     * For single-turn traces this is equivalent to `getAllToolOutputs()`.
+     * For multi-turn traces it excludes tool outputs from earlier turns
+     * so that rules evaluate only the data relevant to the current answer.
+     */
+    getActiveToolOutputs(trace) {
+        const activeTurn = exports.TraceUtils.getActiveTurn(trace);
+        if (!activeTurn)
+            return [];
+        return activeTurn.toolOutputs.flatMap((s) => s.toolOutputs ?? []);
+    },
+    /**
+     * Return whether the trace contains multiple conversation turns.
+     */
+    isMultiTurn(trace) {
+        return exports.TraceUtils.getConversationTurns(trace).length > 1;
+    },
+    /**
+     * Build a virtual single-turn trace from the active (last) conversation turn.
+     *
+     * For multi-turn traces, the grounding engine should evaluate ONLY the
+     * active turn's response against the active turn's tool data. This method
+     * creates a new Trace that contains:
+     *
+     * 1. The original system_prompt (if present)
+     * 2. The active turn's user_input
+     * 3. The active turn's tool_call steps
+     * 4. The active turn's tool_output steps
+     * 5. The active turn's final_response
+     *
+     * The contextual user input (with history prepended) is used so that
+     * rules can understand follow-up references like "what about March?".
+     *
+     * Returns the original trace unmodified if it has only 1 turn.
+     */
+    buildActiveTurnTrace(trace) {
+        const turns = exports.TraceUtils.getConversationTurns(trace);
+        if (turns.length <= 1)
+            return trace;
+        const active = turns[turns.length - 1];
+        const systemPrompt = exports.TraceUtils.getSystemPrompt(trace);
+        const contextualInput = exports.TraceUtils.getContextualUserInput(trace);
+        const steps = [];
+        // 1. System prompt (shared across turns)
+        if (systemPrompt) {
+            steps.push(systemPrompt);
+        }
+        // 2. User input with conversational context
+        steps.push({
+            stepId: `active_user_input`,
+            role: 'user_input',
+            content: contextualInput,
+        });
+        // 3. Active turn's tool calls
+        for (const step of active.toolCalls) {
+            steps.push(step);
+        }
+        // 4. Active turn's tool outputs
+        for (const step of active.toolOutputs) {
+            steps.push(step);
+        }
+        // 5. Active turn's final response
+        if (active.response) {
+            steps.push({
+                stepId: `active_final_response`,
+                role: 'final_response',
+                content: active.response,
+            });
+        }
+        return {
+            traceId: trace.traceId,
+            steps,
+            startedAt: trace.startedAt,
+            endedAt: trace.endedAt,
+            totalLatencyMs: trace.totalLatencyMs,
+            metadata: {
+                ...trace.metadata,
+                multiTurn: true,
+                turnCount: turns.length,
+                activeTurnIndex: turns.length - 1,
+                activeUserInput: active.userInput,
+            },
+        };
+    },
+    // -----------------------------------------------------------------------
+    // Trace normalizer — converts external formats to TG internal format
+    // -----------------------------------------------------------------------
+    /**
+     * Normalise a trace in-place so that external formats (OpenAI chat,
+     * Anthropic Messages, custom integrations) are mapped to TG's canonical
+     * step roles.
+     *
+     * This is **idempotent**: calling it on an already-normalised trace is safe.
+     *
+     * Recognised external patterns:
+     * - OpenAI: `assistant` with `tool_calls[]` → `tool_call`
+     * - OpenAI: `role: 'tool'` or `role: 'function'` → `tool_output`
+     * - Anthropic: `assistant` with `content[].type === 'tool_use'` → `tool_call`
+     * - Anthropic: `user` with `content[].type === 'tool_result'` → `tool_output`
+     * - Custom: `function_call` → `tool_call`; `function_output`/`tool_response` → `tool_output`
+     * - Role aliases: `system`/`instructions` → `system_prompt`; `human`/`user` → `user_input`
+     * - Content-only steps: parses JSON from content into toolCalls/toolOutputs when missing
+     */
+    normalizeTrace(trace) {
+        if (!trace?.steps?.length)
+            return trace;
+        const normalized = [];
+        for (const step of trace.steps) {
+            const role = (step.role ?? '');
+            const raw = step;
+            // --- OpenAI: assistant with tool_calls → tool_call step ---
+            if (role === 'assistant' && hasToolCallsPayload(raw)) {
+                const tcArr = extractOpenAIToolCalls(raw);
+                if (tcArr.length > 0) {
+                    normalized.push({
+                        ...step,
+                        role: 'tool_call',
+                        toolCalls: tcArr,
+                    });
+                    continue;
+                }
+            }
+            // --- OpenAI: role 'tool' or 'function' → tool_output ---
+            if (role === 'tool' || role === 'function') {
+                const output = tryParseJSON(step.content);
+                const toolName = (raw['name'] ??
+                    raw['toolName'] ?? 'unknown');
+                normalized.push({
+                    ...step,
+                    role: 'tool_output',
+                    toolOutputs: step.toolOutputs ?? [{ toolName, output }],
+                });
+                continue;
+            }
+            // --- Custom: function_call → tool_call ---
+            if (role === 'function_call') {
+                normalized.push({ ...step, role: 'tool_call' });
+                continue;
+            }
+            // --- Custom: function_output / tool_response → tool_output ---
+            if (role === 'function_output' || role === 'tool_response') {
+                const output = tryParseJSON(step.content);
+                normalized.push({
+                    ...step,
+                    role: 'tool_output',
+                    toolOutputs: step.toolOutputs ?? [{
+                            toolName: (raw['name'] ??
+                                raw['toolName'] ?? 'unknown'),
+                            output,
+                        }],
+                });
+                continue;
+            }
+            // --- Anthropic: assistant with tool_use content blocks ---
+            if (role === 'assistant' && hasAnthropicToolUse(raw)) {
+                const tcArr = extractAnthropicToolCalls(raw);
+                if (tcArr.length > 0) {
+                    normalized.push({
+                        ...step,
+                        role: 'tool_call',
+                        toolCalls: tcArr,
+                    });
+                    continue;
+                }
+            }
+            // --- Anthropic: user with tool_result content blocks ---
+            if (role === 'user' && hasAnthropicToolResult(raw)) {
+                const outputs = extractAnthropicToolResults(raw);
+                if (outputs.length > 0) {
+                    normalized.push({
+                        ...step,
+                        role: 'tool_output',
+                        toolOutputs: outputs,
+                    });
+                    continue;
+                }
+            }
+            // --- tool_output step with content but no toolOutputs → parse content ---
+            if (role === 'tool_output' && !step.toolOutputs?.length && step.content) {
+                const output = tryParseJSON(step.content);
+                // Detect "tool-name-only" outputs: when content is just a function
+                // name echoed back (e.g. "get_payroll_summary") instead of actual
+                // data.  These carry zero grounding information and should be treated
+                // as empty so that downstream verdicts become UNVERIFIABLE instead of
+                // a misleading UNGROUNDED / hallucinated_entity.
+                const contentStr = step.content.trim();
+                const isToolNameOnly = typeof output === 'string' &&
+                    /^[a-zA-Z_][a-zA-Z0-9_.:-]*$/.test(contentStr);
+                // Also check if the content matches the preceding tool_call's toolName
+                const prevStep = normalized[normalized.length - 1];
+                const prevToolName = prevStep?.role === 'tool_call'
+                    ? (prevStep.toolCalls?.[0]?.toolName ?? '')
+                    : '';
+                const matchesPrevToolName = prevToolName !== '' &&
+                    contentStr.toLowerCase() === prevToolName.toLowerCase();
+                const isNameOnly = isToolNameOnly || matchesPrevToolName;
+                const effectiveOutput = isNameOnly ? null : output;
+                const toolName = (matchesPrevToolName ? prevToolName : undefined) ??
+                    (raw['toolName'] ?? raw['name'] ?? 'unknown');
+                normalized.push({
+                    ...step,
+                    toolOutputs: [{
+                            toolName,
+                            output: effectiveOutput,
+                        }],
+                    // Preserve info about tool-name-only detection so downstream
+                    // modules (TraceReadiness, Rules, Advisor) can give targeted feedback.
+                    ...(isNameOnly ? { metadata: { ...step.metadata, _toolNameOnly: contentStr } } : {}),
+                });
+                continue;
+            }
+            // --- tool_call step with content but no toolCalls → try to parse ---
+            if (role === 'tool_call' && !step.toolCalls?.length && step.content) {
+                const parsed = tryParseJSON(step.content);
+                if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                    const obj = parsed;
+                    const toolName = (obj['name'] ?? obj['toolName'] ??
+                        raw['toolName'] ?? 'unknown');
+                    const params = (obj['parameters'] ?? obj['arguments'] ?? obj['input'] ?? {});
+                    normalized.push({
+                        ...step,
+                        toolCalls: [{ toolName, parameters: params }],
+                    });
+                    continue;
+                }
+            }
+            // --- Map common role aliases ---
+            if (role === 'system' || role === 'instructions') {
+                normalized.push({ ...step, role: 'system_prompt' });
+                continue;
+            }
+            if (role === 'human' || role === 'user') {
+                normalized.push({ ...step, role: 'user_input' });
+                continue;
+            }
+            if (role === 'assistant' && !step.toolCalls?.length) {
+                // Plain assistant message → final_response (only if it has content)
+                if (step.content?.trim()) {
+                    normalized.push({ ...step, role: 'final_response' });
+                    continue;
+                }
+            }
+            // Pass through already-canonical roles unchanged
+            normalized.push(step);
+        }
+        trace.steps = normalized;
+        return trace;
+    },
+    /**
+     * Infer the temporal period from tool call parameters and tool output metadata.
+     *
+     * Checks (in priority order):
+     *   1. Explicit date range params (startDate/endDate, from/to)
+     *   2. Month param (month: "2024-01" or "January 2024")
+     *   3. Year param (year: 2024)
+     *   4. Period range in tool output (period.from / period.to)
+     *   5. Relative params (days: 7, period: "this_month")
+     *
+     * Returns a normalised ISO-ish string or undefined.
+     */
+    inferPeriod(trace) {
+        // --- Source 1: tool call parameters ---
+        const toolCalls = exports.TraceUtils.getAllToolCalls(trace);
+        for (const tc of toolCalls) {
+            const p = tc.parameters;
+            if (!p || typeof p !== 'object')
+                continue;
+            // 1a. Explicit date range: startDate+endDate or from+to
+            const rangeStart = findDateParam(p, ['startDate', 'start_date', 'from', 'dateFrom', 'date_from']);
+            const rangeEnd = findDateParam(p, ['endDate', 'end_date', 'to', 'dateTo', 'date_to']);
+            if (rangeStart && rangeEnd)
+                return `${rangeStart}/${rangeEnd}`;
+            if (rangeStart)
+                return rangeStart;
+            // 1b. Single date param
+            const singleDate = findDateParam(p, ['date']);
+            if (singleDate)
+                return singleDate;
+            // 1c. Month param: "2024-01", "2024-12", "January 2024", "januar 2024"
+            const monthVal = findParam(p, ['month', 'mesec']);
+            if (monthVal !== undefined) {
+                const norm = normaliseMonth(String(monthVal));
+                if (norm)
+                    return norm;
+            }
+            // 1d. Year + quarter
+            const quarterVal = findParam(p, ['quarter', 'kvartal']);
+            const yearVal = findParam(p, ['year', 'godina']);
+            if (quarterVal !== undefined && yearVal !== undefined) {
+                const q = String(quarterVal).replace(/^q/i, '').trim();
+                return `${yearVal}-Q${q}`;
+            }
+            // 1e. Year only
+            if (yearVal !== undefined)
+                return String(yearVal);
+            // 1f. Relative days
+            const daysVal = findParam(p, ['days', 'dana']);
+            if (typeof daysVal === 'number' && daysVal > 0)
+                return `last_${daysVal}_days`;
+            // 1g. Named period
+            const periodVal = findParam(p, ['period', 'period_type']);
+            if (typeof periodVal === 'string' && periodVal.length > 0)
+                return periodVal;
+        }
+        // --- Source 2: tool output period metadata ---
+        const toolOutputs = exports.TraceUtils.getAllToolOutputs(trace);
+        for (const to of toolOutputs) {
+            const output = to.output;
+            if (output && typeof output === 'object' && !Array.isArray(output)) {
+                const obj = output;
+                const periodObj = obj['period'];
+                if (periodObj && typeof periodObj === 'object' && !Array.isArray(periodObj)) {
+                    const po = periodObj;
+                    const from = po['from'] ?? po['start'];
+                    const to2 = po['to'] ?? po['end'];
+                    if (typeof from === 'string' && typeof to2 === 'string') {
+                        return `${from}/${to2}`;
+                    }
+                }
+            }
+        }
+        return undefined;
+    },
+};
+//# sourceMappingURL=index.js.map