truthguard-ai 0.1.0

package/dist-npm/Trace/index.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Trace SDK
+ *
+ * Provides a fluent builder for constructing agent execution traces and
+ * utility helpers for querying them.
+ */
+import type { Trace, TraceId, TraceStep, TraceStepRole, ToolCall, ToolOutput } from '../types';
+/** Options for creating a new trace. */
+export interface TraceBuilderOptions {
+    traceId?: TraceId;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 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();
+ * ```
+ */
+export declare class TraceBuilder {
+    private readonly traceId;
+    private readonly steps;
+    private readonly metadata;
+    private readonly startedAt;
+    constructor(options?: TraceBuilderOptions);
+    /** Add a system prompt step (static context/instructions). */
+    addSystemPrompt(content: string, meta?: Partial<TraceStep>): this;
+    /** Add a user input step. */
+    addUserInput(content: string, meta?: Partial<TraceStep>): this;
+    /** Add a tool call step. */
+    addToolCall(toolName: string, parameters: Record<string, unknown>, meta?: Partial<TraceStep>): this;
+    /** Add a tool output step. */
+    addToolOutput(toolName: string, output: unknown, meta?: Partial<TraceStep>): this;
+    /** Add an LLM call step (e.g., intermediate reasoning). */
+    addLlmCall(content: string, meta?: Partial<TraceStep>): this;
+    /** Add the final response step. */
+    addFinalResponse(content: string, meta?: Partial<TraceStep>): this;
+    /** Low-level step addition. */
+    addStep(role: TraceStepRole, content: string, meta?: Partial<TraceStep>): this;
+    /** Build and return the completed {@link Trace}. */
+    build(): Trace;
+}
+/**
+ * A single conversation turn extracted from a trace.
+ *
+ * In multi-turn traces the steps encode a sequence of Q&A exchanges:
+ *   [user_input] → [tool_call/tool_output]* → [final_response]
+ *
+ * Each such exchange is one turn. The **active turn** is the last one
+ * (the one whose response the pipeline evaluates). Earlier turns are
+ * conversation history that provides context for follow-up questions.
+ *
+ * This is a generic concept — not tied to any specific AI agent platform.
+ */
+export interface ConversationTurn {
+    /** The de-duplicated user question for this turn. */
+    userInput: string;
+    /** All tool call steps that belong to this turn. */
+    toolCalls: TraceStep[];
+    /** All tool output steps that belong to this turn. */
+    toolOutputs: TraceStep[];
+    /** The final_response text for this turn (empty string if missing). */
+    response: string;
+    /** True when this is the last (active) turn being evaluated. */
+    isActive: boolean;
+}
+/** Utility helpers for querying a {@link Trace}. */
+export declare const TraceUtils: {
+    /**
+     * Return all steps matching a given role.
+     */
+    getStepsByRole(trace: Trace, role: TraceStepRole): TraceStep[];
+    /**
+     * Return the final response step, or undefined if not present.
+     */
+    getFinalResponse(trace: Trace): TraceStep | undefined;
+    /**
+     * Return all tool outputs flattened from all tool_output steps.
+     */
+    getAllToolOutputs(trace: Trace): ToolOutput[];
+    /**
+     * Return all tool calls flattened from all tool_call steps.
+     */
+    getAllToolCalls(trace: Trace): ToolCall[];
+    /**
+     * Return all tool output steps (with their stepId preserved).
+     */
+    getToolOutputSteps(trace: Trace): TraceStep[];
+    /**
+     * 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: Trace): boolean;
+    /**
+     * Return the system prompt step, or undefined if not present.
+     */
+    getSystemPrompt(trace: Trace): TraceStep | undefined;
+    /**
+     * Serialise a trace to a JSON string.
+     */
+    toJSON(trace: Trace): string;
+    /**
+     * Deserialise a trace from a JSON string.
+     */
+    fromJSON(json: string): Trace;
+    /**
+     * 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: Trace): ConversationTurn[];
+    /**
+     * Return the active (last) conversation turn, or `undefined` for
+     * single-step traces with no `user_input`.
+     */
+    getActiveTurn(trace: Trace): ConversationTurn | 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: Trace): string;
+    /**
+     * 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: Trace): string;
+    /**
+     * 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: Trace): ToolOutput[];
+    /**
+     * Return whether the trace contains multiple conversation turns.
+     */
+    isMultiTurn(trace: Trace): boolean;
+    /**
+     * 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: Trace): Trace;
+    /**
+     * 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: Trace): 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: Trace): string | undefined;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist-npm/Trace/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Trace/index.ts"],"names":[],"mappings":"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"}