akm-cli 0.9.17-alpha.4 → 0.9.17-alpha.6

package/dist/llm/graph-extract.js

@@ -33,6 +33,12 @@ import { callStructured } from "./structured-call.js";
  * Chosen to be visually clear and unlikely to appear verbatim in asset bodies.
  */
 const BATCH_ASSET_SEPARATOR = "=== ASSET";
+/**
+ * Part of the extractor id that keys cached extractions; the prompt text is
+ * not. Bump it with any change to either prompt, and expect every cached file
+ * to be extracted again. Pending for the next bump (GR-D12): the batch prompt
+ * still asks for "file/dir names", which the single-asset prompt rules out.
+ */
 export const GRAPH_EXTRACT_PROMPT_VERSION = "v3";
 /** Asset bodies longer than this are chunked instead of truncated. */
 const MAX_CHUNK_BODY_CHARS = 1600;
@@ -165,7 +171,13 @@ function normalizeRelationType(raw) {
         return "integrates with";
     return normalized;
 }
-function normalizeEntityKey(raw) {
+/**
+ * The key under which two entity names are the same entity: the display
+ * clean-up above, case-folded. The one normalization for graph entities:
+ * extraction deduplicates on it, the pass deduplicates on it before writing,
+ * and it is the stored `entity_norm` that `related` joins on (GR-D17).
+ */
+export function normalizeEntityKey(raw) {
     return normalizeEntityName(raw).toLowerCase();
 }
 function bumpTelemetry(telemetry, key, amount = 1) {
@@ -173,6 +185,36 @@ function bumpTelemetry(telemetry, key, amount = 1) {
         return;
     telemetry[key] = (telemetry[key] ?? 0) + amount;
 }
+/**
+ * `Promise.all(items.map(fn))` with at most `limit` calls in flight, so the
+ * per-asset calls of one batch never outnumber the chunk pool's concurrency
+ * (GR-D14). The first rejection rejects the map and stops further calls.
+ */
+async function mapWithConcurrency(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    let failed = false;
+    const worker = async () => {
+        while (!failed && next < items.length) {
+            const index = next++;
+            try {
+                results[index] = await fn(items[index]);
+            }
+            catch (error) {
+                failed = true;
+                throw error;
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(Math.max(1, limit), items.length) }, worker));
+    return results;
+}
+/** Count what the parser dropped from one parsed extraction (single-asset or batch item). */
+function bumpFilterTelemetry(telemetry, extraction) {
+    bumpTelemetry(telemetry, "filteredGenericEntities", extraction.filteredGenericEntities ?? 0);
+    bumpTelemetry(telemetry, "filteredInvalidRelations", extraction.filteredInvalidRelations ?? 0);
+    bumpTelemetry(telemetry, "filteredLowConfidenceRelations", extraction.filteredLowConfidenceRelations ?? 0);
+}
 function normalizeBatchState(state) {
     if (!state)
         return undefined;
@@ -512,7 +554,7 @@ async function callGraphLlm(runner, messages, request, onNotices) {
 function parseBatchItem(raw) {
     return parseGraphExtraction(raw);
 }
-function applySuccessfulBatchResults(results, batchResult, nonEmptyBodies, nonEmptyIndices, batchState) {
+function applySuccessfulBatchResults(results, batchResult, nonEmptyBodies, nonEmptyIndices, batchState, telemetry) {
     if (batchState)
         batchState.nonArrayBatchFailures = 0;
     if (batchResult.length > nonEmptyBodies.length) {
@@ -523,8 +565,11 @@ function applySuccessfulBatchResults(results, batchResult, nonEmptyBodies, nonEm
         const originalIndex = nonEmptyIndices[j];
         if (originalIndex === undefined)
             continue;
-        if (j < batchResult.length)
-            results[originalIndex] = parseBatchItem(batchResult[j]);
+        if (j >= batchResult.length)
+            continue;
+        const extraction = parseBatchItem(batchResult[j]);
+        bumpFilterTelemetry(telemetry, extraction);
+        results[originalIndex] = extraction;
     }
 }
 /**
@@ -538,8 +583,8 @@ function applySuccessfulBatchResults(results, batchResult, nonEmptyBodies, nonEm
  * `bodies.length`, missing indices are filled by falling back to individual
  * `extractGraphFromBody` calls — ensuring every input always has a result.
  *
- * Returns an array of the same length as `bodies` (never shorter).
- * Individual elements default to `{entities:[], relations:[]}` on failure.
+ * Returns an array of the same length as `bodies` (never shorter). A body
+ * whose extraction failed gets no entities and `status: "failed"`.
  *
  * Routes through `tryLlmFeature("graph_extraction", ...)` so the feature gate
  * and onFallback hook are honoured uniformly.
@@ -561,6 +606,11 @@ export async function extractGraphFromBodies(llmRunner, bodies, signal, akmConfi
         const result = await extractGraphFromBody(llmRunner, bodies[0] ?? "", signal, akmConfig, onFallback, options);
         return [result];
     }
+    const concurrency = llmRunner.connection.concurrency ?? 1;
+    const extractOne = (body) => extractGraphFromBody(llmRunner, body, signal, akmConfig, onFallback, options);
+    // With batching disabled every body takes the single-asset path, once.
+    if (batchState?.batchingDisabled)
+        return mapWithConcurrency(bodies, concurrency, extractOne);
     // Filter out bodies that are empty so we don't waste tokens, but keep
     // index correspondence by tracking which indices were non-empty.
     const results = bodies.map(empty);
@@ -579,28 +629,18 @@ export async function extractGraphFromBodies(llmRunner, bodies, signal, akmConfi
             }
         }
     }
-    if (oversizedIndices.length > 0) {
-        await Promise.all(oversizedIndices.map(async (index) => {
-            results[index] = await extractGraphFromBody(llmRunner, bodies[index] ?? "", signal, akmConfig, onFallback, options);
-        }));
-    }
+    await mapWithConcurrency(oversizedIndices, concurrency, async (index) => {
+        results[index] = await extractOne(bodies[index] ?? "");
+    });
     if (nonEmptyBodies.length === 0)
         return results;
-    if (batchState?.batchingDisabled) {
-        return Promise.all(bodies.map((body) => extractGraphFromBody(llmRunner, body, signal, akmConfig, onFallback, options)));
-    }
     const systemPrompt = buildBatchSystemPrompt();
     const userPrompt = buildBatchUserPrompt(nonEmptyBodies);
     // Same responseSchema lift as extractGraphFromBody (R12b), scoped to this
     // batch's asset count so a compliant provider bounds every element's
     // entities/relations by the same maxItems as the single-asset path.
     const batchResponseSchema = buildBatchResponseSchema(nonEmptyBodies.length);
-    const truncatedBodies = nonEmptyBodies.filter((body) => body.length > MAX_BATCH_BODY_CHARS).length;
-    if (truncatedBodies > 0) {
-        warnVerbose(`graph extraction (batch): ${truncatedBodies}/${nonEmptyBodies.length} asset body/bodies exceed the batch body threshold of ${MAX_BATCH_BODY_CHARS} chars.`);
-    }
     let batchContextError = false;
-    let nonArrayResponse = false;
     // R2: a dead/erroring provider must not be hammered with a per-asset
     // fallback retry for every body in the batch — that is what turned one
     // outage into 15,453 additional retry attempts. `isTransportFailure`
@@ -609,7 +649,8 @@ export async function extractGraphFromBodies(llmRunner, bodies, signal, akmConfi
     // provider itself is failing (a dead endpoint more often raises
     // `network_error` or `provider_html_error` than a plain 5xx), not that this
     // particular response was malformed; skip the fallback and record every
-    // asset as failed instead.
+    // asset as failed instead. A batch that got no answer at all (the gate's
+    // timeout, or a closed gate) is handled the same way.
     let batchProviderError = false;
     const batchOutcome = await tryLlmFeature("graph_extraction", akmConfig, async () => {
         try {
@@ -646,7 +687,6 @@ export async function extractGraphFromBodies(llmRunner, bodies, signal, akmConfi
                 parsed = retryRaw ? parseEmbeddedJsonResponse(retryRaw, { expect: "array" }) : undefined;
             }
             if (!Array.isArray(parsed)) {
-                nonArrayResponse = true;
                 bumpTelemetry(options.telemetry, "nonArrayBatchFailures");
                 if (batchState) {
                     batchState.nonArrayBatchFailures += 1;
@@ -683,16 +723,20 @@ export async function extractGraphFromBodies(llmRunner, bodies, signal, akmConfi
             }
             return { kind: "value", value: null };
         }
-    }, { kind: "value", value: null }, {
+    }, { kind: "no-answer" }, {
         timeoutMs: llmRunner.timeoutMs,
         onFallback,
     });
     if (batchOutcome.kind === "config-error")
         throw batchOutcome.error;
-    const batchResult = batchOutcome.value;
+    if (batchOutcome.kind === "no-answer") {
+        batchProviderError = true;
+        bumpTelemetry(options.telemetry, "failureCount", nonEmptyBodies.length);
+    }
+    const batchResult = batchOutcome.kind === "value" ? batchOutcome.value : null;
     // Map successful batch results back to their original indices.
     if (batchResult !== null) {
-        applySuccessfulBatchResults(results, batchResult, nonEmptyBodies, nonEmptyIndices, batchState);
+        applySuccessfulBatchResults(results, batchResult, nonEmptyBodies, nonEmptyIndices, batchState, options.telemetry);
     }
     else if (batchProviderError) {
         // No per-asset fallback against a failing provider — record every asset
@@ -736,26 +780,23 @@ export async function extractGraphFromBodies(llmRunner, bodies, signal, akmConfi
             warn(`graph extraction (batch): response had ${batchResult.length} items for ${nonEmptyBodies.length} assets; ` +
                 `falling back to individual calls for ${fallbackIndices.length} missing asset(s).`);
         }
-        await Promise.all(fallbackIndices.map(async (origIdx) => {
-            const body = bodies[origIdx] ?? "";
-            results[origIdx] = await extractGraphFromBody(llmRunner, body, signal, akmConfig, onFallback, options);
-        }));
+        await mapWithConcurrency(fallbackIndices, concurrency, async (origIdx) => {
+            results[origIdx] = await extractOne(bodies[origIdx] ?? "");
+        });
     }
     else if (batchContextError) {
         warn(`graph extraction (batch): skipped ${nonEmptyBodies.length} asset(s) due to context size error; ` +
             `consider increasing llm.contextLength or reducing index.graph.graphExtractionBatchSize to 1.`);
     }
-    else if (nonArrayResponse && batchState?.batchingDisabled) {
-        warn("graph extraction (batch): disabling batching for the rest of this run after repeated non-array responses.");
-    }
     return results;
 }
 /**
  * Extract entities and relations from a single asset body via the configured LLM.
  *
- * Returns `{entities: [], relations: []}` on any failure (timeout, invalid
- * JSON, empty response). Errors are logged via `warn()` but never thrown — a
- * failed extraction for one asset must not abort the rest of the index pass.
+ * Any failure (timeout, invalid JSON, empty response, provider error) returns
+ * no entities with `status: "failed"`, which is never cached, so the next run
+ * retries it. Errors are logged via `warn()` but never thrown — a failed
+ * extraction for one asset must not abort the rest of the index pass.
  *
  * Routes through `tryLlmFeature("graph_extraction", ...)` so the feature gate
  * and onFallback hook are honoured uniformly (Fix C5).
@@ -819,18 +860,15 @@ export async function extractGraphFromBody(llmRunner, body, signal, akmConfig, o
         },
         onNotices: options.onNotices,
         parse: (raw) => {
-            if (!raw)
-                return empty();
-            const parsed = parseEmbeddedJsonResponse(raw);
+            // An empty response is not JSON either; "nothing to extract" is `{"entities": []}`.
+            const parsed = raw ? parseEmbeddedJsonResponse(raw) : undefined;
             if (!parsed) {
                 warn("graph extraction: invalid JSON response from LLM; skipping asset.");
                 bumpTelemetry(options.telemetry, "failureCount");
                 return empty("invalid_json", "failed");
             }
             const extraction = parseGraphExtraction(parsed);
-            bumpTelemetry(options.telemetry, "filteredGenericEntities", extraction.filteredGenericEntities ?? 0);
-            bumpTelemetry(options.telemetry, "filteredInvalidRelations", extraction.filteredInvalidRelations ?? 0);
-            bumpTelemetry(options.telemetry, "filteredLowConfidenceRelations", extraction.filteredLowConfidenceRelations ?? 0);
+            bumpFilterTelemetry(options.telemetry, extraction);
             if (extraction.status === "failed")
                 bumpTelemetry(options.telemetry, "failureCount");
             return extraction;
@@ -854,7 +892,9 @@ export async function extractGraphFromBody(llmRunner, body, signal, akmConfig, o
                 return empty("llm_error", "failed");
             }
         },
-        fallback: empty(),
+        // No answer from the model (the gate's timeout, or a closed gate) is a
+        // failure the next run retries, never a cacheable "no entities".
+        fallback: empty("llm_error", "failed"),
         onFallback,
     });
     if (truncatedChunkCount > 0)