react-native-ai-core 0.1.0 → 0.2.0

package/lib/module/structured.js

@@ -0,0 +1,729 @@
+"use strict";
+
+import { Platform } from 'react-native';
+import { z } from 'zod';
+import NativeAiCore from "./NativeAiCore.js";
+export class StructuredOutputError extends Error {
+  constructor(message, rawResponse, issues = []) {
+    super(message);
+    this.name = 'StructuredOutputError';
+    this.rawResponse = rawResponse;
+    this.issues = issues;
+  }
+}
+const STRUCTURED_PROMPT_BUDGET = 2600;
+const STRUCTURED_REPAIR_RESPONSE_BUDGET = 1200;
+const STRUCTURED_ISSUES_BUDGET = 600;
+const STRUCTURED_CONTINUATION_BUDGET = 1400;
+const DEFAULT_MAX_STRUCTURED_CONTINUATIONS = 8;
+const CONTINUATION_OVERLAP_WINDOW = 160;
+const DEFAULT_STRUCTURED_TIMEOUT_MS = 300000; // 5 min default
+const QUOTA_ERROR_CODE = 9;
+const QUOTA_RETRY_DELAY_MS = 1800;
+const MAX_QUOTA_RETRIES = 2;
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+function toErrorMessage(error) {
+  if (error instanceof Error) return error.message;
+  if (typeof error === 'string') return error;
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}
+function readNumericErrorCode(error) {
+  if (typeof error === 'object' && error !== null) {
+    const directCode = error.errorCode;
+    if (typeof directCode === 'number') return directCode;
+    const code = error.code;
+    if (typeof code === 'number') return code;
+    if (typeof code === 'string') {
+      const parsed = Number.parseInt(code, 10);
+      if (Number.isFinite(parsed)) return parsed;
+    }
+  }
+  const message = toErrorMessage(error);
+  const match = message.match(/error\s*code\s*[:=]?\s*(\d+)/i);
+  if (!match) return null;
+  const capturedCode = match[1];
+  if (!capturedCode) return null;
+  const parsed = Number.parseInt(capturedCode, 10);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function isQuotaError(error) {
+  const code = readNumericErrorCode(error);
+  if (code === QUOTA_ERROR_CODE) return true;
+  const message = toErrorMessage(error).toLowerCase();
+  return message.includes('out of quota') || message.includes('quota exceeded') || message.includes('error code: 9');
+}
+function truncateStart(text, maxChars) {
+  if (text.length <= maxChars) return text;
+  return text.slice(text.length - maxChars);
+}
+function truncateEnd(text, maxChars) {
+  if (text.length <= maxChars) return text;
+  return text.slice(0, maxChars);
+}
+function compactWhitespace(text) {
+  return text.replace(/\s+/g, ' ').trim();
+}
+function stringifyInput(value, maxChars) {
+  return truncateStart(JSON.stringify(value, null, 2), maxChars);
+}
+function fitStructuredPrompt(parts) {
+  return truncateStart(parts.filter(Boolean).join('\n'), STRUCTURED_PROMPT_BUDGET);
+}
+function fitContinuationPrompt(parts) {
+  return truncateStart(parts.filter(Boolean).join('\n'), STRUCTURED_CONTINUATION_BUDGET);
+}
+function zodTypeToDescription(schema) {
+  if (schema instanceof z.ZodString) return 'string';
+  if (schema instanceof z.ZodNumber) return 'number';
+  if (schema instanceof z.ZodBoolean) return 'boolean';
+  if (schema instanceof z.ZodNull) return 'null';
+  if (schema instanceof z.ZodEnum) {
+    return `enum(${schema.options.map(value => JSON.stringify(value)).join(', ')})`;
+  }
+  if (schema instanceof z.ZodLiteral) {
+    return `literal(${JSON.stringify(schema.value)})`;
+  }
+  if (schema instanceof z.ZodArray) {
+    return `Array<${zodTypeToDescription(schema.element)}>`;
+  }
+  if (schema instanceof z.ZodOptional) {
+    return `${zodTypeToDescription(schema.unwrap())} | undefined`;
+  }
+  if (schema instanceof z.ZodNullable) {
+    return `${zodTypeToDescription(schema.unwrap())} | null`;
+  }
+  if (schema instanceof z.ZodUnion) {
+    return schema.options.map(option => zodTypeToDescription(option)).join(' | ');
+  }
+  if (schema instanceof z.ZodObject) {
+    const shape = schema.shape;
+    const entries = Object.entries(shape).map(([key, value]) => `  ${key}: ${zodTypeToDescription(value)}`);
+    return `{
+${entries.join(',\n')}
+}`;
+  }
+  return 'unknown';
+}
+function formatIssues(error) {
+  return error.issues.map(issue => ({
+    path: issue.path.join('.') || '$',
+    message: issue.message
+  }));
+}
+function extractFencedJson(text) {
+  const match = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  return match?.[1]?.trim() ?? null;
+}
+function extractBalancedJson(text) {
+  let start = -1;
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let index = 0; index < text.length; index++) {
+    const char = text[index];
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === '\\') {
+        escaped = true;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      continue;
+    }
+    if (char === '{' || char === '[') {
+      if (depth === 0) start = index;
+      depth++;
+      continue;
+    }
+    if (char === '}' || char === ']') {
+      depth--;
+      if (depth === 0 && start >= 0) {
+        return text.slice(start, index + 1);
+      }
+    }
+  }
+  return null;
+}
+function extractJsonPayload(raw) {
+  const trimmed = raw.trim();
+  const fenced = extractFencedJson(trimmed);
+  if (fenced) return fenced;
+  const balanced = extractBalancedJson(trimmed);
+  if (balanced) return balanced;
+  return trimmed;
+}
+function stripCodeFences(text) {
+  return text.replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/i, '');
+}
+function mergeStructuredFragments(existing, incoming) {
+  const normalizedIncoming = stripCodeFences(incoming).trimStart();
+  if (!normalizedIncoming) return existing;
+  if (!existing) return normalizedIncoming;
+  const maxOverlap = Math.min(CONTINUATION_OVERLAP_WINDOW, existing.length, normalizedIncoming.length);
+  for (let size = maxOverlap; size > 0; size--) {
+    if (existing.endsWith(normalizedIncoming.slice(0, size))) {
+      return existing + normalizedIncoming.slice(size);
+    }
+  }
+  return existing + normalizedIncoming;
+}
+function looksLikeIncompleteJson(text) {
+  const candidate = extractJsonPayload(text).trim();
+  if (!candidate) return false;
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let index = 0; index < candidate.length; index++) {
+    const char = candidate[index];
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === '\\') {
+        escaped = true;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      continue;
+    }
+    if (char === '{' || char === '[') {
+      depth++;
+      continue;
+    }
+    if (char === '}' || char === ']') {
+      depth = Math.max(0, depth - 1);
+    }
+  }
+  const lastChar = candidate[candidate.length - 1];
+  return inString || depth > 0 || lastChar === ',' || lastChar === ':';
+}
+function buildStructuredContinuationPrompt(prompt, outputSchema, partialResponse, input) {
+  const schemaDescription = truncateEnd(zodTypeToDescription(outputSchema), 700);
+  const normalizedPrompt = truncateEnd(compactWhitespace(prompt), 500);
+  const serializedInput = input === undefined ? '' : `Input JSON:\n${stringifyInput(input, 500)}`;
+  const partialTail = truncateStart(stripCodeFences(partialResponse), 900);
+  return fitContinuationPrompt(['Continue the same JSON value from the next character.', 'Do not restart, repeat, explain, summarize, or wrap in markdown.', 'Output only the missing suffix needed to complete the same valid JSON.', 'Schema:', schemaDescription, `Task:\n${normalizedPrompt}`, serializedInput, 'Current partial JSON tail:', partialTail]);
+}
+function buildJsonParseIssues(error) {
+  if (error instanceof z.ZodError) {
+    return formatIssues(error);
+  }
+  if (error instanceof Error) {
+    return [{
+      path: '$',
+      message: error.message
+    }];
+  }
+  return [{
+    path: '$',
+    message: 'Unknown structured output error'
+  }];
+}
+async function generateStructuredRawResponse(prompt, output, input, maxContinuations, timeoutMs) {
+  let combined = await generateStatelessWithQuotaRetry(buildStructuredPrompt(prompt, output, input), timeoutMs);
+  for (let attempt = 0; attempt < maxContinuations; attempt++) {
+    try {
+      JSON.parse(extractJsonPayload(combined));
+      return combined;
+    } catch {
+      if (!looksLikeIncompleteJson(combined)) {
+        return combined;
+      }
+    }
+    const continuationPrompt = buildStructuredContinuationPrompt(prompt, output, combined, input);
+    const continuation = await tryGenerateWithQuotaTolerance(continuationPrompt, timeoutMs);
+    if (continuation === null) {
+      break;
+    }
+    const merged = mergeStructuredFragments(combined, continuation);
+    if (merged === combined) {
+      break;
+    }
+    combined = merged;
+  }
+  return combined;
+}
+function buildStructuredPrompt(prompt, outputSchema, input) {
+  const schemaDescription = truncateEnd(zodTypeToDescription(outputSchema), 900);
+  const normalizedPrompt = truncateEnd(compactWhitespace(prompt), 900);
+  const serializedInput = input === undefined ? '' : `Input JSON:\n${stringifyInput(input, 900)}`;
+  return fitStructuredPrompt(['Return only valid JSON.', 'Do not include markdown, code fences, comments, prose, or explanations.', 'The JSON must match this exact TypeScript-like schema:', schemaDescription, `Task:\n${normalizedPrompt}`, serializedInput]);
+}
+function buildRepairPrompt(prompt, outputSchema, invalidResponse, issues) {
+  const issueText = issues.map(issue => `- ${issue.path}: ${issue.message}`).join('\n');
+  const normalizedIssues = truncateEnd(issueText, STRUCTURED_ISSUES_BUDGET);
+  const normalizedInvalidResponse = truncateStart(compactWhitespace(extractJsonPayload(invalidResponse)), STRUCTURED_REPAIR_RESPONSE_BUDGET);
+  return fitStructuredPrompt([buildStructuredPrompt(prompt, outputSchema), 'Your previous response was invalid.', 'Fix it and return only corrected JSON.', 'Validation errors:', normalizedIssues, 'Previous response:', normalizedInvalidResponse]);
+}
+async function generateStateless(prompt) {
+  if (!NativeAiCore) {
+    throw new Error(`react-native-ai-core: native module unavailable on ${Platform.OS}. This feature requires Android.`);
+  }
+  if (NativeAiCore?.generateResponseStateless) {
+    return NativeAiCore.generateResponseStateless(prompt);
+  }
+  return NativeAiCore.generateResponse(prompt);
+}
+async function generateStatelessWithTimeout(prompt, timeoutMs) {
+  if (timeoutMs <= 0) {
+    return generateStateless(prompt);
+  }
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      reject(new Error(`Structured generation timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([generateStateless(prompt), timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+async function generateStatelessWithQuotaRetry(prompt, timeoutMs) {
+  let quotaRetries = 0;
+  while (true) {
+    try {
+      return await generateStatelessWithTimeout(prompt, timeoutMs);
+    } catch (error) {
+      if (!isQuotaError(error) || quotaRetries >= MAX_QUOTA_RETRIES) {
+        throw error;
+      }
+      quotaRetries += 1;
+      await sleep(QUOTA_RETRY_DELAY_MS);
+    }
+  }
+}
+async function tryGenerateWithQuotaTolerance(prompt, timeoutMs) {
+  try {
+    return await generateStatelessWithQuotaRetry(prompt, timeoutMs);
+  } catch (error) {
+    if (isQuotaError(error)) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+// ── Chunked strategy — tree-walker ───────────────────────────────────────────
+//
+// Walks the schema recursively choosing the optimal call granularity:
+//
+//   • Leaf (string/number/bool/enum) → 1 call with coercion
+//   • Object/array whose schema fits in MAX_COMPACT_SCHEMA_CHARS → 1 walkCompact
+//     call (with continuation if truncated)
+//   • Array of compact elements → askCount + 1 walkCompact per element
+//   • Complex object → per-field walkLeaf/walkCompact
+//
+// This minimises the total number of calls without exceeding the token limit.
+
+const INTER_CALL_DELAY_MS = 100;
+const DEFAULT_ARRAY_COUNT = 5;
+const MAX_ARRAY_COUNT = 7;
+const MAX_WHOLE_ARRAY_COMPACT_ITEMS = 2;
+const LEAF_TIMEOUT_CAP_MS = 15000;
+const COMPACT_TIMEOUT_CAP_MS = 30000;
+const ARRAY_COUNT_TIMEOUT_CAP_MS = 8000;
+const LEAF_MAX_RETRIES_CAP = 1;
+// Schema description length threshold below which a single compact call is used.
+const MAX_COMPACT_SCHEMA_CHARS = 500;
+function readZodLengthValue(value) {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'object' && value !== null) {
+    const maybe = value.value;
+    if (typeof maybe === 'number' && Number.isFinite(maybe)) return maybe;
+  }
+  return null;
+}
+function getArrayBounds(arraySchema, fieldName) {
+  const def = arraySchema._def;
+  const exact = readZodLengthValue(def?.exactLength);
+  const minLen = readZodLengthValue(def?.minLength);
+  const maxLen = readZodLengthValue(def?.maxLength);
+  if (exact !== null) {
+    const fixed = Math.max(0, Math.round(exact));
+    return {
+      min: fixed,
+      max: fixed,
+      preferred: fixed
+    };
+  }
+  let min = minLen !== null ? Math.max(0, Math.round(minLen)) : 1;
+  let max = maxLen !== null ? Math.max(min, Math.round(maxLen)) : MAX_ARRAY_COUNT;
+
+  // Domain heuristics when schema does not constrain lengths explicitly.
+  const name = fieldName.toLowerCase();
+  if (name === 'days') {
+    min = Math.max(min, 7);
+    max = Math.min(max, 7);
+  }
+  if (name === 'exercises') {
+    min = Math.max(min, 3);
+    max = Math.min(max, 4);
+  }
+  const preferred = Math.max(min, Math.min(max, DEFAULT_ARRAY_COUNT));
+  return {
+    min,
+    max,
+    preferred
+  };
+}
+function unwrapModifiers(schema) {
+  if (schema instanceof z.ZodOptional || schema instanceof z.ZodNullable) {
+    return unwrapModifiers(schema.unwrap());
+  }
+  return schema;
+}
+function isLeafSchema(schema) {
+  const inner = unwrapModifiers(schema);
+  return inner instanceof z.ZodString || inner instanceof z.ZodNumber || inner instanceof z.ZodBoolean || inner instanceof z.ZodEnum || inner instanceof z.ZodLiteral || inner instanceof z.ZodNull;
+}
+
+// A schema is "compact" if its description fits within MAX_COMPACT_SCHEMA_CHARS.
+// Arrays are always excluded because their output can multiply by N.
+function isCompactSchema(schema) {
+  const inner = unwrapModifiers(schema);
+  if (isLeafSchema(inner)) return true;
+  if (inner instanceof z.ZodArray) return false;
+  if (hasNestedArray(inner)) return false;
+  return zodTypeToDescription(inner).length <= MAX_COMPACT_SCHEMA_CHARS;
+}
+
+// Returns true if each array element can be generated in a single compact call.
+function isCompactElement(schema) {
+  const inner = unwrapModifiers(schema);
+  if (isLeafSchema(inner)) return true;
+  if (hasNestedArray(inner)) return false;
+  return zodTypeToDescription(inner).length <= MAX_COMPACT_SCHEMA_CHARS;
+}
+
+// Returns true if the schema contains arrays at any depth.
+// Such schemas are never compacted to avoid exceeding the 256-token output limit.
+function hasNestedArray(schema) {
+  const inner = unwrapModifiers(schema);
+  if (inner instanceof z.ZodArray) return true;
+  if (inner instanceof z.ZodObject) {
+    const shape = inner.shape;
+    return Object.values(shape).some(value => hasNestedArray(value));
+  }
+  if (inner instanceof z.ZodUnion) {
+    return inner.options.some(option => hasNestedArray(option));
+  }
+  return false;
+}
+function isStringSchema(schema) {
+  return unwrapModifiers(schema) instanceof z.ZodString;
+}
+function isNumberSchema(schema) {
+  return unwrapModifiers(schema) instanceof z.ZodNumber;
+}
+function isBooleanSchema(schema) {
+  return unwrapModifiers(schema) instanceof z.ZodBoolean;
+}
+function getEnumOptions(schema) {
+  const inner = unwrapModifiers(schema);
+  if (inner instanceof z.ZodEnum) {
+    return [...inner.options];
+  }
+  return null;
+}
+function getLiteralValue(schema) {
+  const inner = unwrapModifiers(schema);
+  if (inner instanceof z.ZodLiteral) {
+    return inner.value;
+  }
+  return null;
+}
+function synthesizeLeafFallback(schema, path) {
+  const inner = unwrapModifiers(schema);
+  const field = (path[path.length - 1] ?? '').toLowerCase();
+  if (inner instanceof z.ZodLiteral) {
+    return inner.value;
+  }
+  if (inner instanceof z.ZodEnum) {
+    // For paths like days.0.day, map index -> weekday to improve coherence.
+    if (field === 'day' && path.length >= 2) {
+      const maybeIndex = Number.parseInt(path[path.length - 2] ?? '', 10);
+      if (Number.isFinite(maybeIndex)) {
+        const idx = Math.max(0, Math.min(inner.options.length - 1, maybeIndex));
+        return inner.options[idx];
+      }
+    }
+    return inner.options[0] ?? null;
+  }
+  if (inner instanceof z.ZodString) {
+    if (field === 'goal') return 'Strength + fat loss';
+    if (field === 'focus') return 'Strength + conditioning';
+    if (field === 'notes') return 'Progressively increase load week to week.';
+    if (field === 'reps') return '8-12';
+    if (field === 'name') return 'Accessory Lift';
+    return 'TBD';
+  }
+  if (inner instanceof z.ZodNumber) {
+    if (field === 'durationweeks') return 1;
+    if (field === 'sets') return 3;
+    if (field === 'restseconds') return 90;
+    return 0;
+  }
+  if (inner instanceof z.ZodBoolean) {
+    return false;
+  }
+  if (inner instanceof z.ZodNull) {
+    return null;
+  }
+  return null;
+}
+function coercePrimitiveField(raw, schema) {
+  const trimmed = raw.trim().replace(/^```[\w]*\n?|```$/g, '').trim();
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    /* sigue */
+  }
+  if (isStringSchema(schema)) return trimmed;
+  if (isNumberSchema(schema)) {
+    const n = Number(trimmed.replace(/[^\d.-]/g, ''));
+    if (!Number.isNaN(n)) return n;
+  }
+  if (isBooleanSchema(schema)) {
+    if (/^true$/i.test(trimmed)) return true;
+    if (/^false$/i.test(trimmed)) return false;
+  }
+  const enumOptions = getEnumOptions(schema);
+  if (enumOptions) {
+    const normalized = trimmed.replace(/^"|"$/g, '').trim();
+    const direct = enumOptions.find(opt => opt === normalized);
+    if (direct) return direct;
+    const ci = enumOptions.find(opt => opt.toLowerCase() === normalized.toLowerCase());
+    if (ci) return ci;
+  }
+  const literalValue = getLiteralValue(schema);
+  if (literalValue !== null) {
+    const normalized = trimmed.replace(/^"|"$/g, '').trim();
+    if (String(literalValue) === normalized) return literalValue;
+  }
+  return null;
+}
+async function walkLeaf(schema, ctx) {
+  const fieldPath = ctx.progressLabel ?? (ctx.path.join('.') || 'root');
+  const fieldName = ctx.path[ctx.path.length - 1] ?? 'value';
+  ctx.onProgress?.(fieldPath, false);
+  const fieldType = truncateEnd(zodTypeToDescription(schema), 200);
+  const itemCtx = ctx.itemHint ? `Context: ${ctx.itemHint}.` : '';
+  const isStr = isStringSchema(schema);
+  const enumOptions = getEnumOptions(schema);
+  const literalValue = getLiteralValue(schema);
+  const valueInstruction = enumOptions ? `one of: ${enumOptions.join(' | ')}. Reply exact value only, no key.` : literalValue !== null ? `exact literal value: ${JSON.stringify(literalValue)}.` : isStr ? 'a plain phrase — no quotes, no JSON' : 'raw JSON value only — no key, no markdown';
+  const prompt = fitStructuredPrompt([`"${fieldName}" (${fieldType}): output ${valueInstruction}.`, `Task: ${truncateEnd(compactWhitespace(ctx.taskPrompt), 250)}`, ctx.input !== undefined ? `Input: ${stringifyInput(ctx.input, 150)}` : '', itemCtx]);
+  const leafTimeoutMs = Math.min(ctx.timeoutMs, LEAF_TIMEOUT_CAP_MS);
+  const leafMaxRetries = Math.min(ctx.maxRetries, LEAF_MAX_RETRIES_CAP);
+  let lastRaw = '';
+  let lastErrorMessage = '';
+  for (let attempt = 0; attempt <= leafMaxRetries; attempt++) {
+    if (attempt > 0) await sleep(INTER_CALL_DELAY_MS);
+    try {
+      lastRaw = await generateStatelessWithQuotaRetry(prompt, leafTimeoutMs);
+      const coerced = coercePrimitiveField(lastRaw, schema);
+      const validated = schema.safeParse(coerced);
+      if (validated.success) {
+        ctx.onProgress?.(fieldPath, true);
+        return validated.data;
+      }
+    } catch (error) {
+      lastErrorMessage = toErrorMessage(error);
+    }
+  }
+  const fallbackFromRaw = isStr ? lastRaw.trim() : null;
+  const fallbackSynth = synthesizeLeafFallback(schema, ctx.path);
+  const fallback = fallbackFromRaw ?? fallbackSynth;
+  const fallbackValidated = schema.safeParse(fallback);
+  if (fallbackValidated.success) {
+    ctx.onProgress?.(fieldPath, true);
+    return fallbackValidated.data;
+  }
+  throw new StructuredOutputError(`Could not generate leaf "${ctx.path.join('.')}"`, lastRaw || lastErrorMessage, [{
+    path: ctx.path.join('.'),
+    message: (lastRaw || lastErrorMessage || 'leaf generation failed').slice(0, 120)
+  }]);
+}
+async function walkCompact(schema, ctx) {
+  const fieldPath = ctx.progressLabel ?? (ctx.path.join('.') || 'root');
+  const fieldName = ctx.path[ctx.path.length - 1] ?? 'value';
+  ctx.onProgress?.(fieldPath, false);
+  const typeDesc = truncateEnd(zodTypeToDescription(schema), 400);
+  const itemCtx = ctx.itemHint ? `Context: ${ctx.itemHint}.` : '';
+  const prompt = fitStructuredPrompt([`"${fieldName}" (${typeDesc}): return JSON value only — no key, no markdown.`, `Task: ${truncateEnd(compactWhitespace(ctx.taskPrompt), 250)}`, ctx.input !== undefined ? `Input: ${stringifyInput(ctx.input, 150)}` : '', itemCtx]);
+  const compactTimeoutMs = Math.min(ctx.timeoutMs, COMPACT_TIMEOUT_CAP_MS);
+  let combined = await generateStatelessWithQuotaRetry(prompt, compactTimeoutMs);
+  for (let cont = 0; cont < 6; cont++) {
+    try {
+      const result = JSON.parse(extractJsonPayload(combined));
+      ctx.onProgress?.(fieldPath, true);
+      return result;
+    } catch {
+      if (!looksLikeIncompleteJson(combined)) break;
+    }
+    await sleep(INTER_CALL_DELAY_MS);
+    const extra = await tryGenerateWithQuotaTolerance(buildStructuredContinuationPrompt(ctx.taskPrompt, schema, combined, ctx.input), compactTimeoutMs);
+    if (!extra) break;
+    const merged = mergeStructuredFragments(combined, extra);
+    if (merged === combined) break;
+    combined = merged;
+  }
+  const finalResult = JSON.parse(extractJsonPayload(combined));
+  ctx.onProgress?.(fieldPath, true);
+  return finalResult;
+}
+async function askArrayCount(arraySchema, fieldName, ctx) {
+  const bounds = getArrayBounds(arraySchema, fieldName);
+  const prompt = fitContinuationPrompt([`"${fieldName}" array count (${bounds.min}-${bounds.max}). Reply: single integer only.`, `Task: ${truncateEnd(compactWhitespace(ctx.taskPrompt), 150)}`]);
+  try {
+    await sleep(INTER_CALL_DELAY_MS);
+    const countTimeoutMs = Math.min(ctx.timeoutMs, ARRAY_COUNT_TIMEOUT_CAP_MS);
+    const raw = await generateStatelessWithQuotaRetry(prompt, countTimeoutMs);
+    const n = parseInt(raw.trim().replace(/\D/g, ''), 10);
+    if (Number.isFinite(n) && n >= bounds.min && n <= bounds.max) return n;
+  } catch {
+    /* usa defecto */
+  }
+  return bounds.preferred;
+}
+async function walkSchema(schema, ctx) {
+  const inner = unwrapModifiers(schema);
+  if (isLeafSchema(inner)) {
+    await sleep(INTER_CALL_DELAY_MS);
+    return walkLeaf(inner, ctx);
+  }
+  if (inner instanceof z.ZodArray) {
+    const elementSchema = unwrapModifiers(inner.element);
+    const fieldName = ctx.path[ctx.path.length - 1] ?? 'items';
+    const arrayLabel = ctx.path.join('.') || fieldName;
+    const count = await askArrayCount(inner, fieldName, ctx);
+
+    // Fast path: if each element fits in a compact call and the array is small,
+    // generate the entire array in one walkCompact call instead of per-element.
+    if (isCompactElement(elementSchema) && count <= MAX_WHOLE_ARRAY_COMPACT_ITEMS) {
+      ctx.onProgress?.(arrayLabel, false);
+      await sleep(INTER_CALL_DELAY_MS);
+      const result = await walkCompact(inner, {
+        ...ctx,
+        progressLabel: arrayLabel
+      });
+      ctx.onProgress?.(arrayLabel, true);
+      return result;
+    }
+
+    // Slow path: non-compact elements → generate one by one
+    ctx.onProgress?.(arrayLabel, false);
+    const items = [];
+    for (let i = 0; i < count; i++) {
+      await sleep(INTER_CALL_DELAY_MS);
+      const elemLabel = `${arrayLabel}[${i + 1}/${count}]`;
+      const elemCtx = {
+        ...ctx,
+        path: [...ctx.path, String(i)],
+        itemHint: `item ${i + 1} of ${count}`,
+        progressLabel: elemLabel
+      };
+      items.push(await walkSchema(elementSchema, elemCtx));
+    }
+    ctx.onProgress?.(arrayLabel, true);
+    return items;
+  }
+
+  // Compact object: single call (except at root where per-field gives better progress).
+  if (isCompactSchema(inner) && ctx.path.length > 0) {
+    await sleep(INTER_CALL_DELAY_MS);
+    return walkCompact(inner, ctx);
+  }
+  if (inner instanceof z.ZodObject) {
+    const shape = inner.shape;
+    const entries = Object.entries(shape);
+    const result = {};
+    const compactEntries = entries.filter(([, s]) => isCompactSchema(s));
+    const complexEntries = entries.filter(([, s]) => !isCompactSchema(s));
+    if (compactEntries.length > 0) {
+      for (const [key, fieldSchema] of compactEntries) {
+        const fieldCtx = {
+          ...ctx,
+          path: [...ctx.path, key],
+          progressLabel: [...ctx.path, key].join('.')
+        };
+        if (isLeafSchema(unwrapModifiers(fieldSchema))) {
+          await sleep(INTER_CALL_DELAY_MS);
+          result[key] = await walkLeaf(fieldSchema, fieldCtx);
+        } else {
+          await sleep(INTER_CALL_DELAY_MS);
+          result[key] = await walkCompact(fieldSchema, fieldCtx);
+        }
+      }
+    }
+    for (const [key, fieldSchema] of complexEntries) {
+      result[key] = await walkSchema(fieldSchema, {
+        ...ctx,
+        path: [...ctx.path, key]
+      });
+    }
+    return result;
+  }
+  await sleep(INTER_CALL_DELAY_MS);
+  return walkLeaf(inner, ctx);
+}
+async function generateChunked(prompt, schema, input, timeoutMs, maxRetries, onProgress) {
+  return walkSchema(schema, {
+    taskPrompt: prompt,
+    input,
+    timeoutMs,
+    maxRetries,
+    path: [],
+    onProgress
+  });
+}
+export async function generateStructuredResponse(options) {
+  const {
+    prompt,
+    output,
+    input,
+    inputSchema,
+    maxRetries = 2,
+    maxContinuations = DEFAULT_MAX_STRUCTURED_CONTINUATIONS,
+    timeoutMs = DEFAULT_STRUCTURED_TIMEOUT_MS,
+    strategy = 'single',
+    onProgress
+  } = options;
+  if (inputSchema && input !== undefined) {
+    inputSchema.parse(input);
+  }
+  if (strategy === 'chunked') {
+    const assembled = await generateChunked(prompt, output, input, timeoutMs, maxRetries, onProgress);
+    return output.parse(assembled);
+  }
+  let lastRawResponse = '';
+  let lastIssues = [];
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    lastRawResponse = attempt === 0 ? await generateStructuredRawResponse(prompt, output, input, maxContinuations, timeoutMs) : await generateStatelessWithQuotaRetry(buildRepairPrompt(prompt, output, lastRawResponse, lastIssues), timeoutMs);
+    try {
+      const parsed = JSON.parse(extractJsonPayload(lastRawResponse));
+      return output.parse(parsed);
+    } catch (error) {
+      lastIssues = buildJsonParseIssues(error);
+      if (attempt === maxRetries) break;
+    }
+  }
+  throw new StructuredOutputError('Unable to produce valid structured output after retries.', lastRawResponse, lastIssues);
+}
+//# sourceMappingURL=structured.js.map