Add timeline engine size routing

api/timeline-stream.php

@@ -13,11 +13,33 @@ $input    = dbnToolsJsonInput(400000);
 $language = dbnToolsNormalizeLanguage($input['language'] ?? 'en');
 
 $_validEngines  = ['nova_lite', 'azure_mini', 'azure_full'];
-$_engine        = in_array((string)($input['engine'] ?? ''), $_validEngines, true)
+$_requestedEngine = in_array((string)($input['engine'] ?? ''), $_validEngines, true)
     ? (string)$input['engine'] : 'azure_mini';
-$_engineCredits = $_engine === 'azure_full' ? 2 : 1;
 
-$ftUid = dbnToolsFreeTierCheckAmount('timeline', $_engineCredits);
+try {
+    $text = dbnToolsInjectDocContent($input, dbnToolsString($input, 'text', 128000, false));
+    if (mb_strlen(trim($text), 'UTF-8') < 10) {
+        dbnToolsError('Paste text, upload a file, or select a document before running.', 422, 'empty_text');
+    }
+
+    $ftUid = dbnToolsIsFreeTier() ? (int)($_SESSION['dbn_tools_sso_uid'] ?? 0) : 0;
+
+    $useMyCase = !empty($input['use_my_case']);
+    if ($useMyCase) {
+        $caseBlock = dbnToolsCaseContext(true, $text, 5);
+        if ($caseBlock !== '') {
+            $text = $text . "\n\n" . $caseBlock;
+        }
+    }
+
+    $timelineRoute = ToolModels::timelineRoute($ftUid, $_requestedEngine, $text);
+    $ftUid = dbnToolsFreeTierCheckAmount('timeline', (int)$timelineRoute['credits']);
+} catch (DbnToolsHttpException $e) {
+    dbnToolsError($e->getMessage(), $e->status, $e->errorCode, $e->extra);
+} catch (Throwable $e) {
+    error_log('timeline-stream preparation error: ' . $e->getMessage());
+    dbnToolsError('The tool could not prepare this request.', 500, 'internal_error');
+}
 
 // Only switch to SSE mode once auth + credit checks pass.
 header('Content-Type: text/event-stream');
@@ -36,17 +58,18 @@ function sseEmit(string $event, array $data): void
 $start = microtime(true);
 
 try {
-    $text = dbnToolsInjectDocContent($input, dbnToolsString($input, 'text', 128000, false));
+    $engine = (string)$timelineRoute['effective_engine'];
-    if (mb_strlen(trim($text), 'UTF-8') < 10) {
+    if (!empty($timelineRoute['auto_upgraded_engine'])) {
-        sseEmit('error', ['code' => 'empty_text', 'message' => 'Paste text, upload a file, or select a document before running.']);
+        $label = match ($engine) {
-        exit;
+            'azure_full' => 'Deep',
+            'azure_mini' => 'Standard',
+            default => 'Quick',
+        };
+        sseEmit('status', [
+            'msg' => 'This input is ' . number_format((int)$timelineRoute['input_char_count']) . " characters, so Timeline is using {$label} for reliability.",
+        ]);
     }
 
-    $validEngines = ['nova_lite', 'azure_mini', 'azure_full'];
-    $engine = in_array((string)($input['engine'] ?? ''), $validEngines, true)
-        ? (string)$input['engine'] : 'azure_mini';
-    $engine = ToolModels::engineForUser($ftUid, $engine);
-
     $validFocus = ['all', 'deadlines', 'hearings', 'cps'];
     $focus = in_array((string)($input['focus'] ?? ''), $validFocus, true)
         ? (string)$input['focus'] : 'all';
@@ -58,14 +81,6 @@ try {
     $includeBackground = ($input['include_background'] ?? true) !== false;
     $userNotes         = dbnToolsString($input, 'user_notes', 2000, false);
 
-    $useMyCase = !empty($input['use_my_case']);
-    if ($useMyCase) {
-        $caseBlock = dbnToolsCaseContext(true, $text, 5);
-        if ($caseBlock !== '') {
-            $text = $text . "\n\n" . $caseBlock;
-        }
-    }
-
     $result = (new DbnLegalToolsService())->timeline(
         $text, $language, $engine, $focus, $confidenceFilter,
         $includeRelative, $includeBackground, $userNotes,
@@ -75,7 +90,12 @@ try {
     $latency = (int)round((microtime(true) - $start) * 1000);
 
     if ($ftUid > 0) {
-        $balance = dbnToolsFreeTierDeductAmount($ftUid, 'timeline', $_engineCredits);
+        $balance = dbnToolsFreeTierDeductAmount($ftUid, 'timeline', (int)$timelineRoute['credits'], [
+            'requested_engine' => $timelineRoute['requested_engine'],
+            'effective_engine' => $timelineRoute['effective_engine'],
+            'auto_upgraded_engine' => $timelineRoute['auto_upgraded_engine'],
+            'input_char_count' => $timelineRoute['input_char_count'],
+        ]);
         $result['balance'] = $balance;
         if (!headers_sent()) {
             header('X-Credits-Remaining: ' . $balance);
@@ -84,6 +104,14 @@ try {
 
     $result['ok']         = true;
     $result['latency_ms'] = $latency;
+    $result['trace_metadata'] = array_merge($result['trace_metadata'] ?? [], [
+        'requested_engine' => $timelineRoute['requested_engine'],
+        'effective_engine' => $timelineRoute['effective_engine'],
+        'auto_upgraded_engine' => $timelineRoute['auto_upgraded_engine'],
+        'input_char_count' => $timelineRoute['input_char_count'],
+        'engine_limit_chars' => $timelineRoute['engine_limit_chars'],
+        'credits_charged' => $timelineRoute['credits'],
+    ]);
 
     dbnToolsLogMetadata([
         'tool'         => 'timeline',

api/timeline.php

@@ -7,34 +7,20 @@ require_once __DIR__ . '/../includes/ToolModels.php';
 dbnToolsRequireMethod('POST');
 dbnToolsRequireAuth();
 $input = dbnToolsJsonInput(400000);
-$_validEngines  = ['nova_lite', 'azure_mini', 'azure_full'];
-$_engine        = in_array((string)($input['engine'] ?? ''), $_validEngines, true)
-    ? (string)$input['engine'] : 'azure_mini';
-$_engineCredits = $_engine === 'azure_full' ? 2 : 1;
-$ftUid    = dbnToolsFreeTierCheckAmount('timeline', $_engineCredits);
 $language = dbnToolsNormalizeLanguage($input['language'] ?? 'en');
+$_validEngines  = ['nova_lite', 'azure_mini', 'azure_full'];
+$_requestedEngine = in_array((string)($input['engine'] ?? ''), $_validEngines, true)
+    ? (string)$input['engine'] : 'azure_mini';
 
-dbnToolsWithChargedTelemetry('timeline', $language, $ftUid, function () use ($input, $language, $ftUid): array {
+$start = microtime(true);
+
+try {
     $text = dbnToolsInjectDocContent($input, dbnToolsString($input, 'text', 128000, false));
     if (mb_strlen(trim($text), 'UTF-8') < 10) {
         dbnToolsAbort('Paste text, upload a file, or select a document before running.', 422, 'empty_text');
     }
 
-    $validEngines = ['nova_lite', 'azure_mini', 'azure_full'];
+    $ftUid = dbnToolsIsFreeTier() ? (int)($_SESSION['dbn_tools_sso_uid'] ?? 0) : 0;
-    $engine = in_array((string)($input['engine'] ?? ''), $validEngines, true)
-        ? (string)$input['engine'] : 'azure_mini';
-    $engine = ToolModels::engineForUser($ftUid, $engine);
-
-    $validFocus = ['all', 'deadlines', 'hearings', 'cps'];
-    $focus = in_array((string)($input['focus'] ?? ''), $validFocus, true)
-        ? (string)$input['focus'] : 'all';
-
-    $confidenceFilter = (string)($input['confidence_filter'] ?? '') === 'high_medium'
-        ? 'high_medium' : 'all';
-
-    $includeRelative   = ($input['include_relative']   ?? true) !== false;
-    $includeBackground = ($input['include_background'] ?? true) !== false;
-    $userNotes         = dbnToolsString($input, 'user_notes', 2000, false);
 
     // Optional: prepend the user's case-context chunks so the timeline includes events
     // referenced in their uploaded case documents.
@@ -46,7 +32,78 @@ dbnToolsWithChargedTelemetry('timeline', $language, $ftUid, function () use ($in
         }
     }
 
+    $timelineRoute = ToolModels::timelineRoute($ftUid, $_requestedEngine, $text);
+    $ftUid = dbnToolsFreeTierCheckAmount('timeline', (int)$timelineRoute['credits']);
+
+    $validFocus = ['all', 'deadlines', 'hearings', 'cps'];
+    $focus = in_array((string)($input['focus'] ?? ''), $validFocus, true)
+        ? (string)$input['focus'] : 'all';
+
+    $confidenceFilter = (string)($input['confidence_filter'] ?? '') === 'high_medium'
+        ? 'high_medium' : 'all';
+
+    $includeRelative   = ($input['include_relative']   ?? true) !== false;
+    $includeBackground = ($input['include_background'] ?? true) !== false;
+    $userNotes         = dbnToolsString($input, 'user_notes', 2000, false);
+    $engine            = (string)$timelineRoute['effective_engine'];
+
     $result = (new DbnLegalToolsService())->timeline($text, $language, $engine, $focus, $confidenceFilter, $includeRelative, $includeBackground, $userNotes, null);
 
-    return $result;
+    if ($ftUid > 0) {
-}, $_engineCredits);
+        $balance = dbnToolsFreeTierDeductAmount($ftUid, 'timeline', (int)$timelineRoute['credits'], [
+            'requested_engine' => $timelineRoute['requested_engine'],
+            'effective_engine' => $timelineRoute['effective_engine'],
+            'auto_upgraded_engine' => $timelineRoute['auto_upgraded_engine'],
+            'input_char_count' => $timelineRoute['input_char_count'],
+        ]);
+        if ($balance >= 0 && !headers_sent()) {
+            header('X-Credits-Remaining: ' . $balance);
+        }
+        $result['balance'] = $balance;
+    }
+
+    $latency = (int)round((microtime(true) - $start) * 1000);
+    $result['ok'] = $result['ok'] ?? true;
+    $result['latency_ms'] = $latency;
+    $result['trace_metadata'] = array_merge($result['trace_metadata'] ?? [], [
+        'requested_engine' => $timelineRoute['requested_engine'],
+        'effective_engine' => $timelineRoute['effective_engine'],
+        'auto_upgraded_engine' => $timelineRoute['auto_upgraded_engine'],
+        'input_char_count' => $timelineRoute['input_char_count'],
+        'engine_limit_chars' => $timelineRoute['engine_limit_chars'],
+        'credits_charged' => $timelineRoute['credits'],
+    ]);
+
+    dbnToolsLogMetadata([
+        'tool' => 'timeline',
+        'language' => $language,
+        'ok' => true,
+        'latency_ms' => $latency,
+        'chunk_count' => (int)($result['trace_metadata']['chunk_count'] ?? 0),
+        'source_count' => (int)($result['trace_metadata']['source_count'] ?? 0),
+        'deployment' => $result['trace_metadata']['deployment'] ?? null,
+    ]);
+
+    dbnToolsRespond($result);
+} catch (DbnToolsHttpException $e) {
+    $latency = (int)round((microtime(true) - $start) * 1000);
+    dbnToolsLogMetadata([
+        'tool' => 'timeline',
+        'language' => $language,
+        'ok' => false,
+        'latency_ms' => $latency,
+        'error_code' => $e->errorCode,
+    ]);
+    dbnToolsError($e->getMessage(), $e->status, $e->errorCode, $e->extra);
+} catch (Throwable $e) {
+    $latency = (int)round((microtime(true) - $start) * 1000);
+    dbnToolsLogMetadata([
+        'tool' => 'timeline',
+        'language' => $language,
+        'ok' => false,
+        'latency_ms' => $latency,
+        'error_code' => 'internal_error',
+    ]);
+    error_log('timeline error: ' . $e->getMessage());
+    dbnToolsError('The tool could not complete this request.', 500, 'internal_error');
+}

assets/js/tools.js

@@ -755,6 +755,21 @@ function currentTimelineEngine() {
   return document.querySelector('input[name="timelineEngine"]:checked')?.value || 'azure_mini';
 }
 
+function timelineEngineLabel(engine) {
+  return {
+    nova_lite: 'Quick',
+    azure_mini: 'Standard',
+    azure_full: 'Deep',
+  }[engine] || 'Timeline';
+}
+
+function timelineClientRoute(engine, charCount) {
+  let effective = engine;
+  if (charCount > 55000) effective = 'azure_full';
+  else if (charCount > 25000 && effective === 'nova_lite') effective = 'azure_mini';
+  return { effective, upgraded: effective !== engine };
+}
+
 function currentTimelineFocus() {
   return document.querySelector('input[name="timelineFocus"]:checked')?.value || 'all';
 }
@@ -1104,14 +1119,19 @@ async function runTool(event) {
     payload.redact_types   = currentRedactTypes();
     lastRedactPayload = { ...payload };
   }
+  let timelineRouteNotice = '';
   if (state.activeTool === 'timeline') {
     payload.engine             = currentTimelineEngine();
+    const clientRoute          = timelineClientRoute(payload.engine, text.length);
     payload.focus              = currentTimelineFocus();
     payload.confidence_filter  = currentConfidenceFilter();
     payload.include_relative   = currentIncludeRelative();
     payload.include_background = currentIncludeBackground();
     payload.user_notes         = (document.getElementById('timelineNotes')?.value || '').trim();
     payload.use_my_case        = (typeof window.dbnGetUseMyCase === 'function') ? window.dbnGetUseMyCase() : false;
+    timelineRouteNotice = clientRoute.upgraded
+      ? `This input is ${text.length.toLocaleString()} characters, so Timeline will use ${timelineEngineLabel(clientRoute.effective)} for reliability.`
+      : '';
   }
 
   lastToolPayload = { ...payload };
@@ -1121,7 +1141,8 @@ async function runTool(event) {
     els.results.innerHTML = '<div class="redact-working" role="status" aria-live="polite"><span class="redact-working__spinner" aria-hidden="true"></span><p>Redacting document…</p></div>';
   }
   if (state.activeTool === 'timeline') {
-    els.results.innerHTML = '<div class="redact-working" id="timelineWorkingState" role="status" aria-live="polite"><span class="redact-working__spinner" aria-hidden="true"></span><p id="timelineStatusMsg">Building timeline…</p></div>';
+    const routeNotice = timelineRouteNotice ? `<p class="upload-hint">${escapeHtml(timelineRouteNotice)}</p>` : '';
+    els.results.innerHTML = `<div class="redact-working" id="timelineWorkingState" role="status" aria-live="polite"><span class="redact-working__spinner" aria-hidden="true"></span><p id="timelineStatusMsg">Building timeline…</p>${routeNotice}</div>`;
   }
   renderTrace([
     { label: 'Query interpretation', detail: 'Preparing request.', status: 'running' },
@@ -1172,7 +1193,11 @@ async function runTool(event) {
     }
     renderResults(data);
     renderTrace(data.trace || []);
-    els.status.textContent = `Done in ${data.latency_ms || 0} ms.`;
+    const routeMeta = data.trace_metadata || {};
+    const serverRouteNotice = state.activeTool === 'timeline' && routeMeta.auto_upgraded_engine
+      ? ` Used ${timelineEngineLabel(routeMeta.effective_engine)} for ${Number(routeMeta.input_char_count || 0).toLocaleString()} characters.`
+      : '';
+    els.status.textContent = `Done in ${data.latency_ms || 0} ms.${serverRouteNotice}`;
     if (['ask', 'redact', 'timeline'].includes(state.activeTool)) {
       showSaveResultButton(state.activeTool, lastToolPayload, data, {
         model: data.trace_metadata?.deployment || null,

includes/ToolModels.php

@@ -11,6 +11,10 @@ require_once __DIR__ . '/FreeTier.php';
  */
 final class ToolModels
 {
+    public const TIMELINE_QUICK_CHAR_LIMIT = 25000;
+    public const TIMELINE_STANDARD_CHAR_LIMIT = 55000;
+    public const TIMELINE_DEEP_CHAR_LIMIT = 128000;
+
     public static function engineForUser(int $userId, string $requestedEngine): string
     {
         $valid = ['nova_lite', 'azure_mini', 'azure_full', 'gpu', 'regex'];
@@ -26,4 +30,52 @@ final class ToolModels
             default => in_array($requestedEngine, ['nova_lite', 'regex'], true) ? $requestedEngine : 'nova_lite',
         };
     }
+
+    public static function timelineRoute(int $userId, string $requestedEngine, string $text): array
+    {
+        $valid = ['nova_lite', 'azure_mini', 'azure_full'];
+        $requestedEngine = in_array($requestedEngine, $valid, true) ? $requestedEngine : 'azure_mini';
+        $tierEngine = self::engineForUser($userId, $requestedEngine);
+        $charCount = mb_strlen($text, 'UTF-8');
+
+        if ($charCount > self::TIMELINE_DEEP_CHAR_LIMIT) {
+            throw new DbnToolsHttpException(
+                'This timeline input is too large after selected documents or My Case context were added. Split the file or use fewer selected documents.',
+                413,
+                'timeline_input_too_large',
+                ['input_char_count' => $charCount, 'max_chars' => self::TIMELINE_DEEP_CHAR_LIMIT]
+            );
+        }
+
+        $effectiveEngine = $tierEngine;
+        if ($charCount > self::TIMELINE_STANDARD_CHAR_LIMIT) {
+            $effectiveEngine = 'azure_full';
+        } elseif ($charCount > self::TIMELINE_QUICK_CHAR_LIMIT && $effectiveEngine === 'nova_lite') {
+            $effectiveEngine = 'azure_mini';
+        }
+
+        return [
+            'requested_engine' => $requestedEngine,
+            'tier_engine' => $tierEngine,
+            'effective_engine' => $effectiveEngine,
+            'auto_upgraded_engine' => $effectiveEngine !== $tierEngine,
+            'input_char_count' => $charCount,
+            'engine_limit_chars' => self::timelineEngineLimit($effectiveEngine),
+            'credits' => self::timelineCredits($effectiveEngine),
+        ];
+    }
+
+    public static function timelineCredits(string $engine): int
+    {
+        return $engine === 'azure_full' ? 2 : 1;
+    }
+
+    public static function timelineEngineLimit(string $engine): int
+    {
+        return match ($engine) {
+            'nova_lite' => self::TIMELINE_QUICK_CHAR_LIMIT,
+            'azure_mini' => self::TIMELINE_STANDARD_CHAR_LIMIT,
+            default => self::TIMELINE_DEEP_CHAR_LIMIT,
+        };
+    }
 }