@semiont/jobs 0.5.9 → 0.5.10

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { JobId, UserId, ResourceId, EntityType, AnnotationId, Annotation, GatheredContext, TagSchema, Logger, EventBus, components, SupportedMediaType } from '@semiont/core';
+import { JobId, UserId, ResourceId, EntityType, AnnotationId, GatheredContext, SupportedMediaType, TagSchema, Logger, EventBus, components } from '@semiont/core';
 import { SemiontProject } from '@semiont/core/node';
 import { InferenceClient } from '@semiont/inference';
 
@@ -74,10 +74,13 @@ interface DetectionParams {
  * Generation job parameters
  */
 interface GenerationParams {
-    referenceId: AnnotationId;
-    sourceResourceId: ResourceId;
-    sourceResourceName: string;
-    annotation: Annotation;
+    /**
+     * The unresolved reference an annotation-focus generation was triggered from.
+     * Absent for resource-focus generation (`yield.fromResource`). When present, the
+     * worker auto-binds the new resource to it; when absent, provenance is a minted
+     * source→derived reference annotation (Fork 2b).
+     */
+    referenceId?: AnnotationId;
     prompt?: string;
     title?: string;
     entityTypes?: EntityType[];
@@ -93,6 +96,13 @@ interface GenerationParams {
     temperature?: number;
     maxTokens?: number;
     storageUri?: string;
+    /**
+     * Requested media type of the generated resource's content. Default `text/markdown`.
+     * The generation worker produces `text/markdown` and `text/plain`; any other value
+     * fails the job (no silent fallback) — Semiont is multi-modal at the core, but
+     * generation coverage is text-only for now and the gap is surfaced, not hidden.
+     */
+    outputMediaType?: SupportedMediaType;
 }
 /**
  * Highlight detection job parameters
@@ -627,7 +637,7 @@ declare class AnnotationDetection {
  * generate German content from an English source resource. See
  * `types.ts` "Locale conventions" for the full discussion.
  */
-declare function generateResourceFromTopic(topic: string, entityTypes: string[], client: InferenceClient, logger: Logger, userPrompt?: string, locale?: string, context?: GatheredContext, temperature?: number, maxTokens?: number, sourceLanguage?: string): Promise<{
+declare function generateResourceFromTopic(topic: string, entityTypes: string[], client: InferenceClient, logger: Logger, userPrompt?: string, locale?: string, context?: GatheredContext, temperature?: number, maxTokens?: number, sourceLanguage?: string, outputMediaType?: SupportedMediaType): Promise<{
     title: string;
     content: string;
 }>;

package/dist/index.js

@@ -1,6 +1,6 @@
 import { promises } from 'fs';
 import * as path from 'path';
-import { jobId, reconcileSelector, isObject, isString, getLocaleEnglishName, didToAgent, isArray } from '@semiont/core';
+import { jobId, deriveViews, reconcileSelector, isObject, isString, getLocaleEnglishName, didToAgent, isArray } from '@semiont/core';
 import { generateAnnotationId } from '@semiont/event-sourcing';
 
 // src/fs-job-queue.ts
@@ -1068,7 +1068,7 @@ Example output:
 function getLanguageName(locale) {
   return getLocaleEnglishName(locale) || locale;
 }
-async function generateResourceFromTopic(topic, entityTypes, client, logger, userPrompt, locale, context, temperature, maxTokens, sourceLanguage) {
+async function generateResourceFromTopic(topic, entityTypes, client, logger, userPrompt, locale, context, temperature, maxTokens, sourceLanguage, outputMediaType = "text/markdown") {
   logger.debug("Generating resource from topic", {
     topicPreview: topic.substring(0, 100),
     entityTypes,
@@ -1088,61 +1088,95 @@ IMPORTANT: Write the entire resource in ${getLanguageName(locale)}.` : "";
 
 The source resource and embedded context are in ${getLanguageName(sourceLanguage)}.` : "";
   let annotationSection = "";
+  let contextSection = "";
+  let resourceSection = "";
+  let graphSection = "";
   if (context) {
-    const parts = [];
-    parts.push(`- Annotation motivation: ${context.annotation.motivation}`);
-    parts.push(`- Source resource: ${context.sourceResource.name}`);
-    const { motivation, body } = context.annotation;
-    if (motivation === "commenting" || motivation === "assessing") {
-      const bodyItem = Array.isArray(body) ? body[0] : body;
-      if (bodyItem && "value" in bodyItem && bodyItem.value) {
-        const label = motivation === "commenting" ? "Comment" : "Assessment";
-        parts.push(`- ${label}: ${bodyItem.value}`);
+    const { focus } = context;
+    const mainResourceId = focus.kind === "annotation" ? focus.sourceResource["@id"] : focus.resource["@id"];
+    const focalAnnotationId = focus.kind === "annotation" ? focus.annotation.id : void 0;
+    if (focus.kind === "annotation") {
+      const parts = [];
+      parts.push(`- Annotation motivation: ${focus.annotation.motivation}`);
+      parts.push(`- Source resource: ${focus.sourceResource.name}`);
+      const { motivation, body } = focus.annotation;
+      if (motivation === "commenting" || motivation === "assessing") {
+        const bodyItem = Array.isArray(body) ? body[0] : body;
+        if (bodyItem && "value" in bodyItem && bodyItem.value) {
+          const label = motivation === "commenting" ? "Comment" : "Assessment";
+          parts.push(`- ${label}: ${bodyItem.value}`);
+        }
       }
-    }
-    annotationSection = `
+      annotationSection = `
 
 Annotation context:
 ${parts.join("\n")}`;
-  }
-  let contextSection = "";
-  if (context?.sourceContext) {
-    const { before, selected, after } = context.sourceContext;
-    contextSection = `
+      if (focus.selected) {
+        const { before, text, after } = focus.selected;
+        contextSection = `
 
 Source document context:
 ---
 ${before ? `...${before}` : ""}
-**[${selected}]**
+**[${text}]**
 ${after ? `${after}...` : ""}
 ---
 `;
-  }
-  let graphContextSection = "";
-  if (context?.graphContext) {
-    const gc = context.graphContext;
-    const connections = gc.connections ?? [];
-    const citedBy = gc.citedBy ?? [];
-    const parts = [];
-    if (connections.length > 0) {
-      const connList = connections.map((c) => `${c.resourceName}${c.entityTypes?.length ? ` (${c.entityTypes.join(", ")})` : ""}`).join(", ");
-      parts.push(`- Connected resources: ${connList}`);
-    }
-    if (gc.citedByCount && gc.citedByCount > 0) {
-      const citedNames = citedBy.map((c) => c.resourceName).join(", ");
-      parts.push(`- This resource is cited by ${gc.citedByCount} other resource${gc.citedByCount > 1 ? "s" : ""}${citedNames ? `: ${citedNames}` : ""}`);
-    }
-    if (gc.siblingEntityTypes && gc.siblingEntityTypes.length > 0) {
-      parts.push(`- Related entity types in this document: ${gc.siblingEntityTypes.join(", ")}`);
-    }
-    if (gc.inferredRelationshipSummary) {
-      parts.push(`- Relationship summary: ${gc.inferredRelationshipSummary}`);
+      }
+    } else {
+      const RESOURCE_CONTENT_CAP = 4e3;
+      const parts = [`- Resource: ${focus.resource.name}`];
+      if (focus.summary) parts.push(`- Summary: ${focus.summary}`);
+      if (focus.suggestedReferences && focus.suggestedReferences.length > 0) {
+        parts.push(`- Suggested references: ${focus.suggestedReferences.join(", ")}`);
+      }
+      resourceSection = `
+
+Resource context:
+${parts.join("\n")}`;
+      if (focus.content?.main) {
+        resourceSection += `
+
+Resource content:
+---
+${focus.content.main.slice(0, RESOURCE_CONTENT_CAP)}
+---`;
+      }
+      const related = Object.entries(focus.content?.related ?? {});
+      if (related.length > 0) {
+        const blocks = related.map(([id, text]) => `[${id}]
+${text.slice(0, RESOURCE_CONTENT_CAP)}`).join("\n\n");
+        resourceSection += `
+
+Related resource content:
+---
+${blocks}
+---`;
+      }
     }
-    if (parts.length > 0) {
-      graphContextSection = `
+    if (mainResourceId) {
+      const views = deriveViews(context.graph, mainResourceId, focalAnnotationId);
+      const parts = [];
+      if (views.connections.length > 0) {
+        const connList = views.connections.map((c) => `${c.resourceName}${c.entityTypes.length ? ` (${c.entityTypes.join(", ")})` : ""}`).join(", ");
+        parts.push(`- Connected resources: ${connList}`);
+      }
+      if (views.citedByCount > 0) {
+        const citedNames = views.citedBy.map((c) => c.resourceName).join(", ");
+        parts.push(`- This resource is cited by ${views.citedByCount} other resource${views.citedByCount > 1 ? "s" : ""}${citedNames ? `: ${citedNames}` : ""}`);
+      }
+      if (views.siblingEntityTypes.length > 0) {
+        parts.push(`- Related entity types in this document: ${views.siblingEntityTypes.join(", ")}`);
+      }
+      if (context.inferredRelationshipSummary) {
+        parts.push(`- Relationship summary: ${context.inferredRelationshipSummary}`);
+      }
+      if (parts.length > 0) {
+        graphSection = `
 
 Knowledge graph context:
 ${parts.join("\n")}`;
+      }
     }
   }
   let semanticContextSection = "";
@@ -1154,17 +1188,20 @@ ${parts.join("\n")}`;
 Related passages from the knowledge base:
 ${lines.join("\n")}`;
   }
-  const structureGuidance = finalMaxTokens >= 1e3 ? "organized into titled sections (## Section) with well-structured paragraphs" : "organized into well-structured paragraphs";
+  const isPlainText = outputMediaType === "text/plain";
+  const structureGuidance = !isPlainText && finalMaxTokens >= 1e3 ? "organized into titled sections (## Section) with well-structured paragraphs" : "organized into well-structured paragraphs";
+  const formatRequirements = isPlainText ? `- Write the response as plain text \u2014 no formatting markup (no #, *, backticks, headings, or links)
+- Begin with the title on its own first line` : `- Start with a clear heading (# Title)
+- Use markdown formatting
+- Write the response as markdown`;
   const prompt = `Generate a concise, informative resource about "${topic}".
 ${entityTypes.length > 0 ? `Focus on these entity types: ${entityTypes.join(", ")}.` : ""}
-${userPrompt ? `Additional context: ${userPrompt}` : ""}${annotationSection}${contextSection}${graphContextSection}${semanticContextSection}${sourceLanguageInstruction}${languageInstruction}
+${userPrompt ? `Additional context: ${userPrompt}` : ""}${annotationSection}${contextSection}${resourceSection}${graphSection}${semanticContextSection}${sourceLanguageInstruction}${languageInstruction}
 
 Requirements:
-- Start with a clear heading (# Title)
 - Aim for approximately ${finalMaxTokens} tokens of content, ${structureGuidance}
 - Be factual and informative
-- Use markdown formatting
-- Write the response as markdown`;
+${formatRequirements}`;
   const parseResponse = (response2) => {
     let content = response2.trim();
     if (content.startsWith("```markdown") || content.startsWith("```md")) {
@@ -1483,6 +1520,13 @@ async function processTagJob(content, inferenceClient, params, userId, generator
   };
 }
 async function processGenerationJob(inferenceClient, params, onProgress, logger) {
+  const GENERATABLE_MEDIA_TYPES = ["text/markdown", "text/plain"];
+  const outputMediaType = params.outputMediaType ?? "text/markdown";
+  if (!GENERATABLE_MEDIA_TYPES.includes(outputMediaType)) {
+    throw new Error(
+      `Unsupported outputMediaType for generation: ${outputMediaType}. Generation produces ${GENERATABLE_MEDIA_TYPES.join(" or ")}.`
+    );
+  }
   onProgress(20, "Fetching context...", "fetching");
   const title = params.title ?? "Untitled";
   const entityTypes = (params.entityTypes ?? []).map(String);
@@ -1497,13 +1541,14 @@ async function processGenerationJob(inferenceClient, params, onProgress, logger)
     params.context,
     params.temperature,
     params.maxTokens,
-    params.sourceLanguage
+    params.sourceLanguage,
+    outputMediaType
   );
   onProgress(85, "Creating resource...", "creating");
   return {
     content: generated.content,
     title: generated.title ?? title,
-    format: "text/markdown",
+    format: outputMediaType,
     result: {
       resourceId: "",
       resourceName: generated.title ?? title