@semiont/jobs 0.5.18 → 0.5.20

package/dist/index.d.ts

@@ -535,7 +535,22 @@ interface GenerationCitation {
  * jobs over SSE and dispatches by jobType to these functions.
  */
 
-type Agent = components['schemas']['Agent'];
+/** A detected span — offsets into the extracted `.text`, plus optional context. */
+type SpanMatch = {
+    exact: string;
+    start: number;
+    end: number;
+    prefix?: string;
+    suffix?: string;
+};
+/**
+ * Turn a detected span into a stored annotation. The media type, resource, and
+ * attribution context are closed over by the caller (see `prepareDetection`);
+ * the detection processor supplies only the motivation, the span, and any
+ * motivation-specific body. This is the single axis that varies by media type,
+ * so the detection processors themselves stay media-agnostic.
+ */
+type BuildAnnotation = (motivation: string, match: SpanMatch, body?: Record<string, unknown> | Record<string, unknown>[]) => Record<string, unknown>;
 /**
  * Progress callback. The three positional args satisfy the minimum
  * `JobProgress` required fields (`percentage`, `message`, `stage`).
@@ -549,11 +564,11 @@ interface ProcessorResult<R> {
     annotations: Record<string, unknown>[];
     result: R;
 }
-declare function processHighlightJob(content: string, inferenceClient: InferenceClient, params: HighlightDetectionParams, userId: string, generator: Agent, onProgress: OnProgress): Promise<ProcessorResult<HighlightDetectionResult>>;
-declare function processCommentJob(content: string, inferenceClient: InferenceClient, params: CommentDetectionParams, userId: string, generator: Agent, onProgress: OnProgress): Promise<ProcessorResult<CommentDetectionResult>>;
-declare function processAssessmentJob(content: string, inferenceClient: InferenceClient, params: AssessmentDetectionParams, userId: string, generator: Agent, onProgress: OnProgress): Promise<ProcessorResult<AssessmentDetectionResult>>;
-declare function processReferenceJob(content: string, inferenceClient: InferenceClient, params: DetectionParams, userId: string, generator: Agent, onProgress: OnProgress, logger: Logger): Promise<ProcessorResult<DetectionResult>>;
-declare function processTagJob(content: string, inferenceClient: InferenceClient, params: TagDetectionParams, userId: string, generator: Agent, onProgress: OnProgress): Promise<ProcessorResult<TagDetectionResult>>;
+declare function processHighlightJob(content: string, inferenceClient: InferenceClient, params: HighlightDetectionParams, buildAnnotation: BuildAnnotation, onProgress: OnProgress): Promise<ProcessorResult<HighlightDetectionResult>>;
+declare function processCommentJob(content: string, inferenceClient: InferenceClient, params: CommentDetectionParams, buildAnnotation: BuildAnnotation, onProgress: OnProgress): Promise<ProcessorResult<CommentDetectionResult>>;
+declare function processAssessmentJob(content: string, inferenceClient: InferenceClient, params: AssessmentDetectionParams, buildAnnotation: BuildAnnotation, onProgress: OnProgress): Promise<ProcessorResult<AssessmentDetectionResult>>;
+declare function processReferenceJob(content: string, inferenceClient: InferenceClient, params: DetectionParams, buildAnnotation: BuildAnnotation, onProgress: OnProgress, logger: Logger): Promise<ProcessorResult<DetectionResult>>;
+declare function processTagJob(content: string, inferenceClient: InferenceClient, params: TagDetectionParams, buildAnnotation: BuildAnnotation, onProgress: OnProgress): Promise<ProcessorResult<TagDetectionResult>>;
 declare function processGenerationJob(inferenceClient: InferenceClient, params: GenerationParams, onProgress: OnProgress, logger: Logger): Promise<{
     content: string;
     title: string;

package/dist/index.js

@@ -1,7 +1,7 @@
 import { promises } from 'fs';
 import * as path from 'path';
-import { jobId, deriveViews, reconcileSelector, isObject, isString, getLocaleEnglishName, didToAgent, isArray } from '@semiont/core';
-import { generateAnnotationId } from '@semiont/event-sourcing';
+import { jobId, deriveViews, reconcileSelector, isObject, isString, getLocaleEnglishName, isArray } from '@semiont/core';
+import '@semiont/event-sourcing';
 import '@semiont/content';
 import '@semiont/observability';
 import '@semiont/sdk';
@@ -1388,12 +1388,15 @@ function annotationDedupeKey(ann) {
   const target = ann.target;
   const selectors = Array.isArray(target?.selector) ? target.selector : [];
   const pos = selectors.find((s) => s.type === "TextPositionSelector");
-  return [
-    ann.motivation,
-    pos?.start ?? "?",
-    pos?.end ?? "?",
-    JSON.stringify(ann.body ?? null)
-  ].join("|");
+  let anchor;
+  if (pos) {
+    anchor = `pos:${pos.start ?? "?"}:${pos.end ?? "?"}`;
+  } else {
+    const frags = selectors.filter((s) => s.type === "FragmentSelector").map((s) => s.value ?? "").join(",");
+    const quote = selectors.find((s) => s.type === "TextQuoteSelector");
+    anchor = `frag:${frags}|quote:${quote?.exact ?? ""}:${quote?.prefix ?? ""}:${quote?.suffix ?? ""}`;
+  }
+  return [ann.motivation, anchor, JSON.stringify(ann.body ?? null)].join("|");
 }
 function dedupeAnnotations(annotations) {
   const seen = /* @__PURE__ */ new Set();
@@ -1406,56 +1409,7 @@ function dedupeAnnotations(annotations) {
   }
   return out;
 }
-function buildTextAnnotation(content, resourceId, userId, generator, motivation, match, body) {
-  if (content.substring(match.start, match.end) !== match.exact) {
-    throw new Error(
-      `buildTextAnnotation invariant: content.substring(${match.start}, ${match.end}) !== exact for resource ${resourceId}, motivation ${motivation}`
-    );
-  }
-  if (match.prefix !== void 0) {
-    const actualPrefix = content.substring(Math.max(0, match.start - match.prefix.length), match.start);
-    if (actualPrefix !== match.prefix) {
-      throw new Error(
-        `buildTextAnnotation invariant: content prefix-slice !== prefix for resource ${resourceId}, motivation ${motivation}`
-      );
-    }
-  }
-  if (match.suffix !== void 0) {
-    const actualSuffix = content.substring(match.end, Math.min(content.length, match.end + match.suffix.length));
-    if (actualSuffix !== match.suffix) {
-      throw new Error(
-        `buildTextAnnotation invariant: content suffix-slice !== suffix for resource ${resourceId}, motivation ${motivation}`
-      );
-    }
-  }
-  const creator = didToAgent(userId);
-  const wasAttributedTo = creator["@id"] === generator["@id"] ? [generator] : [creator, generator];
-  return {
-    "@context": "http://www.w3.org/ns/anno.jsonld",
-    "type": "Annotation",
-    "id": generateAnnotationId(),
-    motivation,
-    creator,
-    generator,
-    wasAttributedTo,
-    created: (/* @__PURE__ */ new Date()).toISOString(),
-    target: {
-      type: "SpecificResource",
-      source: resourceId,
-      selector: [
-        { type: "TextPositionSelector", start: match.start, end: match.end },
-        {
-          type: "TextQuoteSelector",
-          exact: match.exact,
-          ...match.prefix && { prefix: match.prefix },
-          ...match.suffix && { suffix: match.suffix }
-        }
-      ]
-    },
-    ...body !== void 0 ? { body } : {}
-  };
-}
-async function processHighlightJob(content, inferenceClient, params, userId, generator, onProgress) {
+async function processHighlightJob(content, inferenceClient, params, buildAnnotation, onProgress) {
   onProgress(10, "Loading resource...", "analyzing");
   onProgress(30, "Analyzing text...", "analyzing");
   const highlights = await AnnotationDetection.detectHighlights(
@@ -1467,7 +1421,7 @@ async function processHighlightJob(content, inferenceClient, params, userId, gen
   );
   onProgress(60, `Creating ${highlights.length} annotations...`, "creating");
   const annotations = dedupeAnnotations(highlights.map(
-    (h) => buildTextAnnotation(content, params.resourceId, userId, generator, "highlighting", h)
+    (h) => buildAnnotation("highlighting", h)
   ));
   onProgress(100, `Complete! Created ${annotations.length} highlights`, "creating");
   return {
@@ -1475,7 +1429,7 @@ async function processHighlightJob(content, inferenceClient, params, userId, gen
     result: { highlightsFound: highlights.length, highlightsCreated: annotations.length }
   };
 }
-async function processCommentJob(content, inferenceClient, params, userId, generator, onProgress) {
+async function processCommentJob(content, inferenceClient, params, buildAnnotation, onProgress) {
   onProgress(10, "Loading resource...", "analyzing");
   onProgress(30, "Analyzing text...", "analyzing");
   const comments = await AnnotationDetection.detectComments(
@@ -1494,7 +1448,7 @@ async function processCommentJob(content, inferenceClient, params, userId, gener
       // Match the pre-#651 CommentAnnotationWorker: include format and
       // language on the body TextualBody. Optional in the schema, but
       // consumers that do language-aware rendering rely on them.
-      buildTextAnnotation(content, params.resourceId, userId, generator, "commenting", c, [
+      buildAnnotation("commenting", c, [
         { type: "TextualBody", value: c.comment, purpose: "commenting", format: "text/plain", language: bodyLanguage }
       ])
     )
@@ -1505,7 +1459,7 @@ async function processCommentJob(content, inferenceClient, params, userId, gener
     result: { commentsFound: comments.length, commentsCreated: annotations.length }
   };
 }
-async function processAssessmentJob(content, inferenceClient, params, userId, generator, onProgress) {
+async function processAssessmentJob(content, inferenceClient, params, buildAnnotation, onProgress) {
   onProgress(10, "Loading resource...", "analyzing");
   onProgress(30, "Analyzing text...", "analyzing");
   const assessments = await AnnotationDetection.detectAssessments(
@@ -1527,7 +1481,7 @@ async function processAssessmentJob(content, inferenceClient, params, userId, ge
       // purpose='describing' — that loses the "this is an assessment, not
       // a description" signal and breaks existing readers that access
       // `body.value` directly on the object.
-      buildTextAnnotation(content, params.resourceId, userId, generator, "assessing", a, {
+      buildAnnotation("assessing", a, {
         type: "TextualBody",
         value: a.assessment,
         purpose: "assessing",
@@ -1542,7 +1496,7 @@ async function processAssessmentJob(content, inferenceClient, params, userId, ge
     result: { assessmentsFound: assessments.length, assessmentsCreated: annotations.length }
   };
 }
-async function processReferenceJob(content, inferenceClient, params, userId, generator, onProgress, logger) {
+async function processReferenceJob(content, inferenceClient, params, buildAnnotation, onProgress, logger) {
   const entityTypeNames = params.entityTypes.map(String);
   const requestParams = [{ label: "Entity types", value: entityTypeNames.join(", ") }];
   const completedEntityTypes = [];
@@ -1599,15 +1553,7 @@ async function processReferenceJob(content, inferenceClient, params, userId, gen
           anchorMethod: reconciled.anchorMethod
         });
       }
-      const ann = buildTextAnnotation(
-        content,
-        params.resourceId,
-        userId,
-        generator,
-        "linking",
-        toMatch(reconciled),
-        unresolvedBody
-      );
+      const ann = buildAnnotation("linking", toMatch(reconciled), unresolvedBody);
       allAnnotations.push(ann);
       totalEmitted++;
     }
@@ -1619,7 +1565,7 @@ async function processReferenceJob(content, inferenceClient, params, userId, gen
     result: { totalFound, totalEmitted: annotations.length, errors }
   };
 }
-async function processTagJob(content, inferenceClient, params, userId, generator, onProgress) {
+async function processTagJob(content, inferenceClient, params, buildAnnotation, onProgress) {
   onProgress(10, "Loading resource...", "analyzing");
   onProgress(30, "Analyzing text for tags...", "analyzing");
   const allTags = [];
@@ -1638,7 +1584,7 @@ async function processTagJob(content, inferenceClient, params, userId, generator
   const bodyLanguage = params.language ?? "en";
   const annotations = dedupeAnnotations(tags.map((t) => {
     const category = t.category ?? "unknown";
-    return buildTextAnnotation(content, params.resourceId, userId, generator, "tagging", t, [
+    return buildAnnotation("tagging", t, [
       { type: "TextualBody", value: category, purpose: "tagging", format: "text/plain", language: bodyLanguage },
       { type: "TextualBody", value: params.schema.id, purpose: "classifying", format: "text/plain" }
     ]);