Trappan

export async function runOrchestrator(
  company: CompanyInput,
  metrics: MetricDef[],
  options?: { cacheMaxAgeHours?: number },
  runContext?: RunContext
): Promise<OrchestratorResult> {

  // Phase 1 — return early if all metrics are fresh
  const cached = await getCachedMetrics(company.id, metricKeys);
  if (missingMetrics.length === 0) return finalize({ signal: "clean", ... });

  // Phase 2 — find the report PDF
  const discovery = await runWithRetry(
    (note) => findReport({ ...input, _note: note }, { logger: log }),
    { isSuccess: (o) => !!o?.report_url, label: `reportsFinder:${company.id}` }
  );

  // Phase 3 — extract missing metrics
  const { outputs, steps } = await parseMetrics(missingMetrics, reportUrl, ctx);
  await upsertMetrics(company.id, reportUrl, outputs);

  // Phase 4 — persist and return
  return finalize({ signal: deriveSignal(steps, failed), ... });
}

export async function runWithRetry<T>(
  fn: (note: string | null) => Promise<T | null>,
  options: HarnessOptions<T>
): Promise<HarnessResult<T>> {
  let best: T | null = null;
  let bestConfidence: string | null = null;

  for (let attempt = 1; attempt <= totalAttempts; attempt++) {
    const output = await fn(attempt === 1 ? null : retryNote);

    // Promote to best only if strictly higher confidence
    const promoteToBest =
      best === null ||
      (isSuccess(output) && !isSuccess(best)) ||
      (isSuccess(output) === isSuccess(best) &&
        confidenceRank(confidence) > confidenceRank(bestConfidence));

    if (promoteToBest) { best = output; bestConfidence = confidence; }
    if (succeeded) return { output: best, attempts: attempt, succeeded: true };

    await sleep(backoff(attempt)); // exponential, skipped on last attempt
  }

  return { output: best, attempts: totalAttempts, succeeded: false };
}

// Embed the extracted block description, search for matching canonical metric
for (const block of blocks) {
  const matches = await searchDefinitions(block.description); // pgvector cosine search
  const best = matches[0];
  if (!best || best.similarity < DEFINITION_MATCH_THRESHOLD) continue;
  if (!passesGuardrails(best.canonical_key, block)) continue; // e.g. EPRA NRV must say "per aktie"

  // Prepend company label — extraction uses this as its primary search term
  resolved[best.canonical_key] = [block.title, ...defaults];
}

export async function parseMetrics(metrics, reportUrl, ctx) {
  const pdfData = await loadPdf(reportUrl);
  const tier1 = await runTier1(pdfData, metrics, ctx);
  // keyword scan → render candidate pages → vision LLM

  if (tier1.step.accepted) { // confidence === "high" | "medium"
    return buildResult(pdfData, tier1.outputs, [tier1.step], "tier1");
  }

  // Tier 2: web_search_preview on the live PDF URL
  const tier2 = await runTier2(reportUrl, metrics, tier1.resolvedTerms, ctx);
  return buildResult(pdfData, tier2.outputs, [tier1.step, tier2.step], "tier2_fallback");
}

export async function findReport(input, options): Promise<ReportsFinderOutput> {
  // Method 1: mfn.se — structured IR hub, period-accurate
  const mfnResult = await findViaMfn(input, log);
  if (mfnResult.report_url) return mfnResult;

  // Method 2: company website crawl
  const crawlResult = await findViaCrawl(input, log);
  if (crawlResult.report_url) return crawlResult;

  // Method 3: OpenAI web search (last resort)
  return findViaOpenAISearch(input, log);
}