@almadar/llm 1.0.0

package/src/truncation-detector.ts

@@ -0,0 +1,308 @@
+/**
+ * Truncation Detector
+ *
+ * Utilities for detecting when LLM output has been truncated and
+ * extracting usable content from partial responses.
+ *
+ * @packageDocumentation
+ */
+
+import type { LLMFinishReason } from './client.js';
+import { autoCloseJson } from './json-parser.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type TruncationReason =
+  | 'finish_reason'
+  | 'json_incomplete'
+  | 'bracket_mismatch'
+  | 'none';
+
+export interface TruncationResult {
+  isTruncated: boolean;
+  reason: TruncationReason;
+  partialContent?: string;
+  lastCompleteElement?: unknown;
+  missingCloseBrackets?: number;
+  missingCloseBraces?: number;
+}
+
+// ============================================================================
+// Main Detection Function
+// ============================================================================
+
+export function detectTruncation(
+  response: string,
+  finishReason: LLMFinishReason,
+): TruncationResult {
+  if (finishReason === 'length') {
+    const bracketInfo = countBrackets(response);
+    return {
+      isTruncated: true,
+      reason: 'finish_reason',
+      partialContent: response,
+      lastCompleteElement: findLastCompleteElement(response),
+      missingCloseBrackets: bracketInfo.missingCloseBrackets,
+      missingCloseBraces: bracketInfo.missingCloseBraces,
+    };
+  }
+
+  try {
+    JSON.parse(response);
+    return { isTruncated: false, reason: 'none' };
+  } catch {
+    // JSON is invalid, check if due to truncation
+  }
+
+  if (finishReason === 'stop' || finishReason === null) {
+    const trimmed = response.trim();
+
+    const isMidContent =
+      trimmed.endsWith(',') ||
+      trimmed.endsWith(':') ||
+      trimmed.endsWith('": ') ||
+      /:\s*$/.test(trimmed) ||
+      /,\s*$/.test(trimmed);
+
+    if (isMidContent) {
+      const bracketInfo = countBrackets(response);
+      return {
+        isTruncated: true,
+        reason: 'json_incomplete',
+        partialContent: response,
+        lastCompleteElement: findLastCompleteElement(response),
+        missingCloseBrackets: bracketInfo.missingCloseBrackets,
+        missingCloseBraces: bracketInfo.missingCloseBraces,
+      };
+    }
+
+    try {
+      const closed = autoCloseJson(trimmed);
+      JSON.parse(closed);
+      return { isTruncated: false, reason: 'none' };
+    } catch {
+      return { isTruncated: false, reason: 'none' };
+    }
+  }
+
+  const bracketInfo = countBrackets(response);
+  if (
+    bracketInfo.missingCloseBrackets > 0 ||
+    bracketInfo.missingCloseBraces > 0
+  ) {
+    return {
+      isTruncated: true,
+      reason: 'bracket_mismatch',
+      partialContent: response,
+      lastCompleteElement: findLastCompleteElement(response),
+      missingCloseBrackets: bracketInfo.missingCloseBrackets,
+      missingCloseBraces: bracketInfo.missingCloseBraces,
+    };
+  }
+
+  return { isTruncated: false, reason: 'none' };
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+function countBrackets(json: string): {
+  openBrackets: number;
+  closeBrackets: number;
+  openBraces: number;
+  closeBraces: number;
+  missingCloseBrackets: number;
+  missingCloseBraces: number;
+} {
+  let inString = false;
+  let escaped = false;
+  let openBrackets = 0;
+  let closeBrackets = 0;
+  let openBraces = 0;
+  let closeBraces = 0;
+
+  for (const char of json) {
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (char === '\\' && inString) {
+      escaped = true;
+      continue;
+    }
+    if (char === '"') {
+      inString = !inString;
+      continue;
+    }
+    if (inString) continue;
+
+    switch (char) {
+      case '[':
+        openBrackets++;
+        break;
+      case ']':
+        closeBrackets++;
+        break;
+      case '{':
+        openBraces++;
+        break;
+      case '}':
+        closeBraces++;
+        break;
+    }
+  }
+
+  return {
+    openBrackets,
+    closeBrackets,
+    openBraces,
+    closeBraces,
+    missingCloseBrackets: Math.max(0, openBrackets - closeBrackets),
+    missingCloseBraces: Math.max(0, openBraces - closeBraces),
+  };
+}
+
+export function findLastCompleteElement(json: string): unknown | null {
+  const autoClosed = autoCloseJson(json);
+  try {
+    return JSON.parse(autoClosed);
+  } catch {
+    // Auto-close didn't work
+  }
+
+  const trimmed = json.trim();
+
+  if (trimmed.startsWith('[')) {
+    const lastCompleteIndex = findLastCompleteArrayElement(trimmed);
+    if (lastCompleteIndex > 0) {
+      const subset = trimmed.substring(0, lastCompleteIndex) + ']';
+      try {
+        return JSON.parse(subset);
+      } catch {
+        // Continue
+      }
+    }
+  }
+
+  if (trimmed.startsWith('{')) {
+    const closed = autoCloseJson(trimmed);
+    try {
+      return JSON.parse(closed);
+    } catch {
+      const lastCompleteIndex = findLastCompleteObjectProperty(trimmed);
+      if (lastCompleteIndex > 0) {
+        const subset = trimmed.substring(0, lastCompleteIndex) + '}';
+        try {
+          return JSON.parse(subset);
+        } catch {
+          // Give up
+        }
+      }
+    }
+  }
+
+  return null;
+}
+
+function findLastCompleteArrayElement(json: string): number {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  let lastCompleteElementEnd = -1;
+
+  for (let i = 0; i < json.length; i++) {
+    const char = json[i];
+
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (char === '\\' && inString) {
+      escaped = true;
+      continue;
+    }
+    if (char === '"') {
+      inString = !inString;
+      continue;
+    }
+    if (inString) continue;
+
+    if (char === '[' || char === '{') {
+      depth++;
+    } else if (char === ']' || char === '}') {
+      depth--;
+      if (depth === 1) {
+        lastCompleteElementEnd = i + 1;
+      }
+    } else if (char === ',' && depth === 1) {
+      lastCompleteElementEnd = i;
+    }
+  }
+
+  return lastCompleteElementEnd > 0 ? lastCompleteElementEnd : -1;
+}
+
+function findLastCompleteObjectProperty(json: string): number {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  let lastCommaIndex = -1;
+
+  for (let i = 0; i < json.length; i++) {
+    const char = json[i];
+
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (char === '\\' && inString) {
+      escaped = true;
+      continue;
+    }
+    if (char === '"') {
+      inString = !inString;
+      continue;
+    }
+    if (inString) continue;
+
+    if (char === '[' || char === '{') {
+      depth++;
+    } else if (char === ']' || char === '}') {
+      depth--;
+    } else if (char === ',' && depth === 1) {
+      lastCommaIndex = i;
+    }
+  }
+
+  return lastCommaIndex > 0 ? lastCommaIndex : -1;
+}
+
+export function isLikelyTruncated(content: string): boolean {
+  const trimmed = content.trim();
+  if (!trimmed) return false;
+
+  const brackets = countBrackets(trimmed);
+  if (
+    brackets.missingCloseBrackets > 0 ||
+    brackets.missingCloseBraces > 0
+  ) {
+    return true;
+  }
+
+  const abruptEndings = [
+    /,\s*$/,
+    /:\s*$/,
+    /"\s*:\s*$/,
+    /\[\s*$/,
+    /{\s*$/,
+  ];
+
+  for (const pattern of abruptEndings) {
+    if (pattern.test(trimmed)) return true;
+  }
+
+  return false;
+}