@semiont/make-meaning 0.2.34-build.91 → 0.2.34-build.93

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { JobWorker, JobQueue, AnyJob, DetectionResult, RunningJob, DetectionParams, DetectionProgress, GenerationResult, GenerationParams, GenerationProgress, HighlightDetectionResult, HighlightDetectionParams, HighlightDetectionProgress, AssessmentDetectionResult, AssessmentDetectionParams, AssessmentDetectionProgress, CommentDetectionResult, CommentDetectionParams, CommentDetectionProgress, TagDetectionResult, TagDetectionParams, TagDetectionProgress } from '@semiont/jobs';
 import { EventStore } from '@semiont/event-sourcing';
 import { RepresentationStore } from '@semiont/content';
-import { EnvironmentConfig, EventBus, components, StoredEvent, ResourceId, CreationMethod, UserId, AnnotationUri, ResourceAnnotations, AnnotationId, AnnotationCategory, GraphPath, GraphConnection, GenerationContext } from '@semiont/core';
+import { EnvironmentConfig, EventBus, Logger, components, StoredEvent, ResourceId, CreationMethod, UserId, AnnotationUri, ResourceAnnotations, AnnotationId, AnnotationCategory, GraphPath, GraphConnection, GenerationContext } from '@semiont/core';
 import { InferenceClient } from '@semiont/inference';
 import { GraphDatabase } from '@semiont/graph';
 
@@ -27,12 +27,12 @@ interface DetectedAnnotation {
         entityTypes: string[];
     };
 }
-declare class ReferenceDetectionWorker extends JobWorker {
+declare class ReferenceAnnotationWorker extends JobWorker {
     private config;
     private eventStore;
     private inferenceClient;
     private eventBus;
-    constructor(jobQueue: JobQueue, config: EnvironmentConfig, eventStore: EventStore, inferenceClient: InferenceClient, eventBus: EventBus);
+    constructor(jobQueue: JobQueue, config: EnvironmentConfig, eventStore: EventStore, inferenceClient: InferenceClient, eventBus: EventBus, logger: Logger);
     protected getWorkerName(): string;
     protected canProcessJob(job: AnyJob): boolean;
     protected executeJob(job: AnyJob): Promise<DetectionResult>;
@@ -71,7 +71,7 @@ declare class GenerationWorker extends JobWorker {
     private eventStore;
     private inferenceClient;
     private eventBus;
-    constructor(jobQueue: JobQueue, config: EnvironmentConfig, eventStore: EventStore, inferenceClient: InferenceClient, eventBus: EventBus);
+    constructor(jobQueue: JobQueue, config: EnvironmentConfig, eventStore: EventStore, inferenceClient: InferenceClient, eventBus: EventBus, logger: Logger);
     protected getWorkerName(): string;
     protected canProcessJob(job: AnyJob): boolean;
     protected executeJob(job: AnyJob): Promise<GenerationResult>;
@@ -81,6 +81,7 @@ declare class GenerationWorker extends JobWorker {
      * Override base class to emit job.completed event with resultResourceId
      */
     protected emitCompletionEvent(job: RunningJob<GenerationParams, GenerationProgress>, result: GenerationResult): Promise<void>;
+    protected handleJobFailure(job: AnyJob, error: any): Promise<void>;
     /**
      * Update job progress and emit events to Event Store
      * Overrides base class to also emit job progress events
@@ -95,13 +96,13 @@ declare class GenerationWorker extends JobWorker {
  * that should be highlighted and creates highlight annotations.
  */
 
-declare class HighlightDetectionWorker extends JobWorker {
+declare class HighlightAnnotationWorker extends JobWorker {
     private config;
     private eventStore;
     private inferenceClient;
     private eventBus;
     private isFirstProgress;
-    constructor(jobQueue: JobQueue, config: EnvironmentConfig, eventStore: EventStore, inferenceClient: InferenceClient, eventBus: EventBus);
+    constructor(jobQueue: JobQueue, config: EnvironmentConfig, eventStore: EventStore, inferenceClient: InferenceClient, eventBus: EventBus, logger: Logger);
     protected getWorkerName(): string;
     protected canProcessJob(job: AnyJob): boolean;
     protected executeJob(job: AnyJob): Promise<HighlightDetectionResult>;
@@ -126,13 +127,13 @@ declare class HighlightDetectionWorker extends JobWorker {
  * passages in the text and creates assessment annotations.
  */
 
-declare class AssessmentDetectionWorker extends JobWorker {
+declare class AssessmentAnnotationWorker extends JobWorker {
     private config;
     private eventStore;
     private inferenceClient;
     private eventBus;
     private isFirstProgress;
-    constructor(jobQueue: JobQueue, config: EnvironmentConfig, eventStore: EventStore, inferenceClient: InferenceClient, eventBus: EventBus);
+    constructor(jobQueue: JobQueue, config: EnvironmentConfig, eventStore: EventStore, inferenceClient: InferenceClient, eventBus: EventBus, logger: Logger);
     protected getWorkerName(): string;
     protected canProcessJob(job: AnyJob): boolean;
     protected executeJob(job: AnyJob): Promise<AssessmentDetectionResult>;
@@ -157,13 +158,13 @@ declare class AssessmentDetectionWorker extends JobWorker {
  * that would benefit from explanatory comments and creates comment annotations.
  */
 
-declare class CommentDetectionWorker extends JobWorker {
+declare class CommentAnnotationWorker extends JobWorker {
     private config;
     private eventStore;
     private inferenceClient;
     private eventBus;
     private isFirstProgress;
-    constructor(jobQueue: JobQueue, config: EnvironmentConfig, eventStore: EventStore, inferenceClient: InferenceClient, eventBus: EventBus);
+    constructor(jobQueue: JobQueue, config: EnvironmentConfig, eventStore: EventStore, inferenceClient: InferenceClient, eventBus: EventBus, logger: Logger);
     protected getWorkerName(): string;
     protected canProcessJob(job: AnyJob): boolean;
     protected executeJob(job: AnyJob): Promise<CommentDetectionResult>;
@@ -189,13 +190,13 @@ declare class CommentDetectionWorker extends JobWorker {
  * creates tag annotations with dual-body structure.
  */
 
-declare class TagDetectionWorker extends JobWorker {
+declare class TagAnnotationWorker extends JobWorker {
     private config;
     private eventStore;
     private inferenceClient;
     private eventBus;
     private isFirstProgress;
-    constructor(jobQueue: JobQueue, config: EnvironmentConfig, eventStore: EventStore, inferenceClient: InferenceClient, eventBus: EventBus);
+    constructor(jobQueue: JobQueue, config: EnvironmentConfig, eventStore: EventStore, inferenceClient: InferenceClient, eventBus: EventBus, logger: Logger);
     protected getWorkerName(): string;
     protected canProcessJob(job: AnyJob): boolean;
     protected executeJob(job: AnyJob): Promise<TagDetectionResult>;
@@ -227,7 +228,8 @@ declare class GraphDBConsumer {
     private _globalSubscription;
     private processing;
     private lastProcessed;
-    constructor(config: EnvironmentConfig, eventStore: EventStore, graphDb: GraphDatabase);
+    private readonly logger;
+    constructor(config: EnvironmentConfig, eventStore: EventStore, graphDb: GraphDatabase, logger: Logger);
     initialize(): Promise<void>;
     /**
      * Subscribe globally to ALL events (system AND resource events)
@@ -291,17 +293,17 @@ interface MakeMeaningService {
     inferenceClient: InferenceClient;
     graphDb: GraphDatabase;
     workers: {
-        detection: ReferenceDetectionWorker;
+        detection: ReferenceAnnotationWorker;
         generation: GenerationWorker;
-        highlight: HighlightDetectionWorker;
-        assessment: AssessmentDetectionWorker;
-        comment: CommentDetectionWorker;
-        tag: TagDetectionWorker;
+        highlight: HighlightAnnotationWorker;
+        assessment: AssessmentAnnotationWorker;
+        comment: CommentAnnotationWorker;
+        tag: TagAnnotationWorker;
     };
     graphConsumer: GraphDBConsumer;
     stop: () => Promise<void>;
 }
-declare function startMakeMeaning(config: EnvironmentConfig, eventBus: EventBus): Promise<MakeMeaningService>;
+declare function startMakeMeaning(config: EnvironmentConfig, eventBus: EventBus, logger: Logger): Promise<MakeMeaningService>;
 
 /**
  * Entity Types Bootstrap Service
@@ -315,7 +317,7 @@ declare function startMakeMeaning(config: EnvironmentConfig, eventBus: EventBus)
  * Bootstrap entity types projection if it doesn't exist.
  * Uses a system user ID (00000000-0000-0000-0000-000000000000) for bootstrap events.
  */
-declare function bootstrapEntityTypes(eventStore: EventStore, config: EnvironmentConfig): Promise<void>;
+declare function bootstrapEntityTypes(eventStore: EventStore, config: EnvironmentConfig, logger?: Logger): Promise<void>;
 /**
  * Reset the bootstrap flag (used for testing)
  */
@@ -394,6 +396,7 @@ declare class ResourceOperations {
  * - Create annotations (ID generation, validation, event emission)
  * - Update annotation body (operations: add/remove/replace)
  * - Delete annotations (validation, event emission)
+ *
  */
 
 type Annotation$2 = components['schemas']['Annotation'];
@@ -417,7 +420,7 @@ declare class AnnotationOperations {
     /**
      * Delete an annotation
      */
-    static deleteAnnotation(id: string, resourceIdUri: string, userId: UserId, eventStore: EventStore, config: EnvironmentConfig): Promise<void>;
+    static deleteAnnotation(id: string, resourceIdUri: string, userId: UserId, eventStore: EventStore, config: EnvironmentConfig, logger?: Logger): Promise<void>;
     /**
      * Apply body operations (add/remove/replace) to annotation body
      */
@@ -468,6 +471,9 @@ declare class ResourceContext {
  * - Building LLM context for annotations
  * - Extracting annotation text context
  * - Generating AI summaries
+ *
+ * NOTE: This class contains static utility methods without logger access.
+ * Console statements kept for debugging - consider adding logger parameter in future.
  */
 
 type AnnotationLLMContextResponse = components['schemas']['AnnotationLLMContextResponse'];
@@ -490,7 +496,7 @@ declare class AnnotationContext {
      * @returns Rich context for LLM processing
      * @throws Error if annotation or resource not found
      */
-    static buildLLMContext(annotationUri: AnnotationUri, resourceId: ResourceId, config: EnvironmentConfig, options?: BuildContextOptions): Promise<AnnotationLLMContextResponse>;
+    static buildLLMContext(annotationUri: AnnotationUri, resourceId: ResourceId, config: EnvironmentConfig, options?: BuildContextOptions, logger?: Logger): Promise<AnnotationLLMContextResponse>;
     /**
      * Get resource annotations from view storage (fast path)
      * Throws if view missing
@@ -541,7 +547,7 @@ declare class AnnotationContext {
     /**
      * Generate AI summary of annotation in context
      */
-    static generateAnnotationSummary(annotationId: AnnotationId, resourceId: ResourceId, config: EnvironmentConfig): Promise<ContextualSummaryResponse>;
+    static generateAnnotationSummary(annotationId: AnnotationId, resourceId: ResourceId, config: EnvironmentConfig, logger?: Logger): Promise<ContextualSummaryResponse>;
     /**
      * Get resource content as string
      */
@@ -640,6 +646,9 @@ declare class LLMContext {
  * Provides static methods to parse and validate AI responses for each motivation type.
  * Includes offset validation and correction logic.
  * Extracted from worker implementations to centralize parsing logic.
+ *
+ * NOTE: These are static utility methods without logger access.
+ * Console statements kept for debugging - consider adding logger parameter in future.
  */
 /**
  * Represents a detected comment with validated position
@@ -870,12 +879,13 @@ interface ExtractedEntity {
  * @param entityTypes - Array of entity types to detect (optionally with examples)
  * @param client - Inference client for AI operations
  * @param includeDescriptiveReferences - Include anaphoric/cataphoric references (default: false)
+ * @param logger - Optional logger for debugging entity extraction
  * @returns Array of extracted entities with their character offsets
  */
 declare function extractEntities(exact: string, entityTypes: string[] | {
     type: string;
     examples?: string[];
-}[], client: InferenceClient, includeDescriptiveReferences?: boolean): Promise<ExtractedEntity[]>;
+}[], client: InferenceClient, includeDescriptiveReferences?: boolean, logger?: Logger): Promise<ExtractedEntity[]>;
 
 /**
  * Resource Generation Functions
@@ -885,12 +895,13 @@ declare function extractEntities(exact: string, entityTypes: string[] | {
  * - Resource summary generation
  * - Reference suggestion generation
  * - Language handling and template processing
+ *
  */
 
 /**
  * Generate resource content using inference
  */
-declare function generateResourceFromTopic(topic: string, entityTypes: string[], client: InferenceClient, userPrompt?: string, locale?: string, context?: GenerationContext, temperature?: number, maxTokens?: number): Promise<{
+declare function generateResourceFromTopic(topic: string, entityTypes: string[], client: InferenceClient, userPrompt?: string, locale?: string, context?: GenerationContext, temperature?: number, maxTokens?: number, logger?: Logger): Promise<{
     title: string;
     content: string;
 }>;
@@ -914,4 +925,4 @@ declare function generateUuid(): string;
 declare const PACKAGE_NAME = "@semiont/make-meaning";
 declare const VERSION = "0.1.0";
 
-export { AnnotationContext, AnnotationDetection, AnnotationOperations, AssessmentDetectionWorker, type AssessmentMatch, type BuildContextOptions, CommentDetectionWorker, type CommentMatch, type CreateAnnotationResult, type CreateResourceInput, type ExtractedEntity, GenerationWorker, GraphContext, GraphDBConsumer, type GraphEdge, type GraphNode, type GraphRepresentation, HighlightDetectionWorker, type HighlightMatch, LLMContext, type LLMContextOptions, type ListResourcesFilters, type MakeMeaningService, MotivationParsers, MotivationPrompts, PACKAGE_NAME, ReferenceDetectionWorker, ResourceContext, ResourceOperations, TagDetectionWorker, type TagMatch, type UpdateAnnotationBodyResult, type UpdateResourceInput, VERSION, bootstrapEntityTypes, extractEntities, generateReferenceSuggestions, generateResourceFromTopic, generateResourceSummary, generateUuid, readEntityTypesProjection, resetBootstrap, startMakeMeaning };
+export { AnnotationContext, AnnotationDetection, AnnotationOperations, AssessmentAnnotationWorker, type AssessmentMatch, type BuildContextOptions, CommentAnnotationWorker, type CommentMatch, type CreateAnnotationResult, type CreateResourceInput, type ExtractedEntity, GenerationWorker, GraphContext, GraphDBConsumer, type GraphEdge, type GraphNode, type GraphRepresentation, HighlightAnnotationWorker, type HighlightMatch, LLMContext, type LLMContextOptions, type ListResourcesFilters, type MakeMeaningService, MotivationParsers, MotivationPrompts, PACKAGE_NAME, ReferenceAnnotationWorker, ResourceContext, ResourceOperations, TagAnnotationWorker, type TagMatch, type UpdateAnnotationBodyResult, type UpdateResourceInput, VERSION, bootstrapEntityTypes, extractEntities, generateReferenceSuggestions, generateResourceFromTopic, generateResourceSummary, generateUuid, readEntityTypesProjection, resetBootstrap, startMakeMeaning };