@semiont/jobs 0.5.26 → 0.5.28

package/README.md

@@ -30,8 +30,8 @@ npm install @semiont/jobs
 ## Quick Start
 
 ```typescript
-import { FsJobQueue, type PendingJob, type GenerationParams } from '@semiont/jobs';
-import { EventBus, userId, resourceId, annotationId, jobId } from '@semiont/core';
+import { FsJobQueue, type PendingJob, type DetectionParams } from '@semiont/jobs';
+import { EventBus, userId, resourceId, jobId } from '@semiont/core';
 import { SemiontProject } from '@semiont/core/node';
 
 // Initialize — jobs are stored under project.jobsDir
@@ -41,33 +41,34 @@ const jobQueue = new FsJobQueue(project, logger, eventBus);
 await jobQueue.initialize();
 
 // Create a job
-const job: PendingJob<GenerationParams> = {
+const job: PendingJob<DetectionParams> = {
   status: 'pending',
   metadata: {
     id: jobId('job-abc123'),
-    type: 'generation',
+    type: 'reference-annotation',
     userId: userId('user@example.com'),
     userName: 'Jane Doe',
     userEmail: 'jane@example.com',
     userDomain: 'example.com',
     created: new Date().toISOString(),
     retryCount: 0,
-    maxRetries: 3,
+    maxRetries: 1,
   },
   params: {
-    referenceId: annotationId('ref-123'),
-    sourceResourceId: resourceId('doc-456'),
-    sourceResourceName: 'Source Document',
-    annotation: { /* full W3C Annotation */ },
-    title: 'Generated Article',
-    prompt: 'Write about AI',
-    language: 'en-US',
+    resourceId: resourceId('doc-456'),
+    entityTypes: ['Person', 'Organization'],
   },
 };
 
 await jobQueue.createJob(job);
 ```
 
+Generation jobs are enqueued the same way, but their params are a
+[`GenerationJobParams`](./docs/JobTypes.md#generation-generation) bag whose
+`context` carries the anchor — writing one straight to the queue bypasses the
+dispatcher that normally derives and stamps `resourceId` from
+`context.focus`, so prefer `client.yield.fromContext(...)`.
+
 ## Job Types
 
 ```typescript

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { JobId, UserId, ResourceId, EntityType, AnnotationId, GatheredContext, SupportedMediaType, TagSchema, Logger, EventBus, components, Annotation } from '@semiont/core';
+import { JobId, UserId, ResourceId, EntityType, GenerationJobParams, TagSchema, Logger, EventBus, components, Annotation, SupportedMediaType, GatheredContext } from '@semiont/core';
 import { SemiontProject } from '@semiont/core/node';
 import { InferenceClient } from '@semiont/inference';
 
@@ -70,63 +70,6 @@ interface DetectionParams {
     /** Source-resource locale — see locale conventions above. */
     sourceLanguage?: string;
 }
-/**
- * Generation job parameters
- */
-interface GenerationParams {
-    /**
-     * 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[];
-    /** Annotation body locale — language the *generated resource* is written in. */
-    language?: string;
-    /**
-     * Source-resource locale — language of the resource being referenced.
-     * Used in the prompt so the LLM understands the embedded source-context
-     * snippet correctly when source ≠ target language.
-     */
-    sourceLanguage?: string;
-    context?: GatheredContext;
-    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;
-    /**
-     * What the model is asked to DO — the prompt's framing verb. Canonical values map
-     * to tested framings; any other string is used verbatim as the framing instruction
-     * (loud degrade: the worker warns, never silently falls back to 'resource').
-     * Default 'resource'. See .plans/YIELD-STRUCTURE.md.
-     */
-    task?: 'resource' | 'answer' | 'summary' | (string & {});
-    /**
-     * How the output is internally segmented — text-bearing shape, subordinate to
-     * `outputMediaType` (never its peer). Canonical values map to tested guidance; any
-     * other string becomes a freeform "Organize the output as: …" instruction (loud
-     * degrade). UNSET means NO structure directive is emitted — the task framing and
-     * the model determine shape. See .plans/YIELD-STRUCTURE.md D2/D5.
-     */
-    structure?: 'prose' | 'sections' | 'chat' | (string & {});
-    /**
-     * Ask the model to cite: emit `[[<id>]]` transport tokens after each claim, using
-     * the ids the context embedding provides (CONTEXT-IDENTIFIERS). The worker
-     * validates each id against the embedded context (unknown ids are dropped
-     * loudly), strips the tokens from the stored content, and mints W3C linking
-     * annotations on the derived resource. See .plans/INLINE-CITATIONS.md.
-     */
-    cite?: boolean;
-}
 /**
  * Highlight detection job parameters
  */
@@ -186,7 +129,6 @@ interface TagDetectionParams {
 interface DetectionProgress {
     totalEntityTypes: number;
     processedEntityTypes: number;
-    currentEntityType?: string;
     entitiesFound: number;
     entitiesEmitted: number;
 }
@@ -194,6 +136,7 @@ interface DetectionProgress {
  * Detection job result
  */
 interface DetectionResult {
+    kind: 'reference-annotation';
     totalFound: number;
     totalEmitted: number;
     errors: number;
@@ -211,8 +154,11 @@ interface YieldProgress {
  * Generation job result
  */
 interface GenerationResult {
+    kind: 'generation';
     resourceId: ResourceId;
     resourceName: string;
+    /** True when the model stopped at the maxTokens ceiling — the artifact is cut off, not complete (GENERATE-FROM-RESOURCE D6). */
+    truncated: boolean;
 }
 /**
  * Highlight detection job progress
@@ -226,6 +172,7 @@ interface HighlightDetectionProgress {
  * Highlight detection job result
  */
 interface HighlightDetectionResult {
+    kind: 'highlight-annotation';
     highlightsFound: number;
     highlightsCreated: number;
 }
@@ -241,6 +188,7 @@ interface AssessmentDetectionProgress {
  * Assessment detection job result
  */
 interface AssessmentDetectionResult {
+    kind: 'assessment-annotation';
     assessmentsFound: number;
     assessmentsCreated: number;
 }
@@ -256,6 +204,7 @@ interface CommentDetectionProgress {
  * Comment detection job result
  */
 interface CommentDetectionResult {
+    kind: 'comment-annotation';
     commentsFound: number;
     commentsCreated: number;
 }
@@ -274,6 +223,7 @@ interface TagDetectionProgress {
  * Tag detection job result
  */
 interface TagDetectionResult {
+    kind: 'tag-annotation';
     tagsFound: number;
     tagsCreated: number;
     byCategory: Record<string, number>;
@@ -333,7 +283,7 @@ interface CancelledJob<P> {
  */
 type Job<P, PG, R> = PendingJob<P> | RunningJob<P, PG> | CompleteJob<P, R> | FailedJob<P> | CancelledJob<P>;
 type DetectionJob = Job<DetectionParams, DetectionProgress, DetectionResult>;
-type GenerationJob = Job<GenerationParams, YieldProgress, GenerationResult>;
+type GenerationJob = Job<GenerationJobParams, YieldProgress, GenerationResult>;
 type HighlightDetectionJob = Job<HighlightDetectionParams, HighlightDetectionProgress, HighlightDetectionResult>;
 type AssessmentDetectionJob = Job<AssessmentDetectionParams, AssessmentDetectionProgress, AssessmentDetectionResult>;
 type CommentDetectionJob = Job<CommentDetectionParams, CommentDetectionProgress, CommentDetectionResult>;
@@ -541,14 +491,26 @@ type SpanMatch = {
  */
 type BuildAnnotation = (motivation: Motivation, match: SpanMatch, body?: Annotation['body']) => Annotation;
 /**
- * Progress callback. The three positional args satisfy the minimum
- * `JobProgress` required fields (`percentage`, `message`, `stage`).
- * The fourth optional arg carries job-type-specific fields
- * (`currentEntityType`, `completedEntityTypes`, `requestParams`, etc.)
+ * Progress callback. The two positional args are the required `JobProgress`
+ * fields (`percentage`, `message`). The third optional arg carries the
+ * job-type-specific fields (`completedEntityTypes`, `requestParams`, etc.)
  * that the progress UI renders.
- */
-type OnProgress = (percentage: number, message: string, stage: string, extra?: Partial<JobProgress>) => void;
+ *
+ * Anything in `extra` describing the RUN rather than the moment must be passed
+ * on EVERY call: the client's `progress$` replaces its value per event, so a
+ * field sent once disappears on the next tick.
+ *
+ * `message` is a CODE plus typed params, never a prose sentence
+ * (ASSIST-PROGRESS-CONSOLIDATION A6). The producer reports what happened;
+ * each client renders it in the user's language — react-ui from its 29
+ * locales, the Go launcher from its English map. The vocabulary is frozen
+ * by the census of these call sites: adding a shape means adding a variant
+ * to `JobProgressMessage.json` and copy in every client, not composing a
+ * new sentence here.
+ */
+type OnProgress = (percentage: number, message: JobProgressMessage, extra?: Partial<JobProgress>) => void;
 type JobProgress = components['schemas']['JobProgress'];
+type JobProgressMessage = components['schemas']['JobProgressMessage'];
 /** The five W3C motivations this system mints — a closed vocabulary, so it is
  *  typed as one rather than as `string`. */
 type Motivation = Annotation['motivation'];
@@ -561,7 +523,7 @@ declare function processCommentJob(content: string, inferenceClient: InferenceCl
 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<{
+declare function processGenerationJob(inferenceClient: InferenceClient, params: GenerationJobParams, onProgress: OnProgress, logger: Logger): Promise<{
     content: Uint8Array;
     title: string;
     format: SupportedMediaType;
@@ -645,7 +607,7 @@ declare class AnnotationDetection {
      * (source-resource locale). See `types.ts` "Locale conventions" for the
      * full discussion.
      */
-    static detectComments(content: string, client: InferenceClient, instructions?: string, tone?: string, density?: number, language?: string, sourceLanguage?: string, onChunk?: (completedChunks: number, totalChunks: number) => void): Promise<CommentMatch[]>;
+    static detectComments(content: string, client: InferenceClient, instructions?: string, tone?: string, density?: number, language?: string, sourceLanguage?: string, onActivity?: (completedChunks: number, totalChunks: number) => void): Promise<CommentMatch[]>;
     /**
      * Detect highlights in content.
      *
@@ -653,7 +615,7 @@ declare class AnnotationDetection {
      * applies, used in the prompt so the LLM analyzes non-English source
      * correctly.
      */
-    static detectHighlights(content: string, client: InferenceClient, instructions?: string, density?: number, sourceLanguage?: string, onChunk?: (completedChunks: number, totalChunks: number) => void): Promise<HighlightMatch[]>;
+    static detectHighlights(content: string, client: InferenceClient, instructions?: string, density?: number, sourceLanguage?: string, onActivity?: (completedChunks: number, totalChunks: number) => void): Promise<HighlightMatch[]>;
     /**
      * Detect assessments in content.
      *
@@ -661,7 +623,7 @@ declare class AnnotationDetection {
      * (annotation body locale). `sourceLanguage` is the locale of the content
      * being analyzed (source-resource locale).
      */
-    static detectAssessments(content: string, client: InferenceClient, instructions?: string, tone?: string, density?: number, language?: string, sourceLanguage?: string, onChunk?: (completedChunks: number, totalChunks: number) => void): Promise<AssessmentMatch[]>;
+    static detectAssessments(content: string, client: InferenceClient, instructions?: string, tone?: string, density?: number, language?: string, sourceLanguage?: string, onActivity?: (completedChunks: number, totalChunks: number) => void): Promise<AssessmentMatch[]>;
     /**
      * Detect tags in content for a specific category.
      *
@@ -674,7 +636,7 @@ declare class AnnotationDetection {
      * identifiers, not LLM-generated text — so it's consumed at the body-stamp
      * site, not here.
      */
-    static detectTags(content: string, client: InferenceClient, schema: TagSchema, category: string, sourceLanguage?: string, onChunk?: (completedChunks: number, totalChunks: number) => void): Promise<TagMatch[]>;
+    static detectTags(content: string, client: InferenceClient, schema: TagSchema, category: string, sourceLanguage?: string, onActivity?: (completedChunks: number, totalChunks: number) => void): Promise<TagMatch[]>;
 }
 
 /**
@@ -700,6 +662,7 @@ declare function generateResourceFromTopic(topic: string, entityTypes: string[],
 }): Promise<{
     title: string;
     content: string;
+    truncated: boolean;
 }>;
 
 /**
@@ -735,4 +698,4 @@ declare function generateResourceFromTopic(topic: string, entityTypes: string[],
 declare const STALL_THRESHOLD_MS: number;
 
 export { AnnotationDetection, FsJobQueue, STALL_THRESHOLD_MS, generateResourceFromTopic, isCancelledJob, isCompleteJob, isFailedJob, isPendingJob, isRunningJob, processAssessmentJob, processCommentJob, processGenerationJob, processHighlightJob, processReferenceJob, processTagJob };
-export type { AnyJob, AssessmentDetectionJob, AssessmentDetectionParams, AssessmentDetectionProgress, AssessmentDetectionResult, CancelledJob, CommentDetectionJob, CommentDetectionParams, CommentDetectionProgress, CommentDetectionResult, CompleteJob, DetectionJob, DetectionParams, DetectionProgress, DetectionResult, FailedJob, GenerationJob, GenerationParams, GenerationResult, HighlightDetectionJob, HighlightDetectionParams, HighlightDetectionProgress, HighlightDetectionResult, JobMetadata, JobQueryFilters, JobQueue, JobStatus, JobType, OnProgress, PendingJob, ProcessorResult, RunningJob, TagDetectionJob, TagDetectionParams, TagDetectionProgress, TagDetectionResult, YieldProgress };
+export type { AnyJob, AssessmentDetectionJob, AssessmentDetectionParams, AssessmentDetectionProgress, AssessmentDetectionResult, CancelledJob, CommentDetectionJob, CommentDetectionParams, CommentDetectionProgress, CommentDetectionResult, CompleteJob, DetectionJob, DetectionParams, DetectionProgress, DetectionResult, FailedJob, GenerationJob, GenerationResult, HighlightDetectionJob, HighlightDetectionParams, HighlightDetectionProgress, HighlightDetectionResult, JobMetadata, JobQueryFilters, JobQueue, JobStatus, JobType, OnProgress, PendingJob, ProcessorResult, RunningJob, TagDetectionJob, TagDetectionParams, TagDetectionProgress, TagDetectionResult, YieldProgress };