@semiont/make-meaning 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,236 @@
+import { components, AnnotationUri } from '@semiont/api-client';
+import { ResourceId, EnvironmentConfig, ResourceAnnotations, AnnotationId, AnnotationCategory, GraphPath, GraphConnection } from '@semiont/core';
+import { CommentMatch, HighlightMatch, AssessmentMatch, TagMatch } from '@semiont/inference';
+export { AssessmentMatch, CommentMatch, HighlightMatch, TagMatch } from '@semiont/inference';
+
+/**
+ * Resource Context
+ *
+ * Assembles resource context from view storage and content store
+ * Does NOT touch the graph - graph queries go through GraphContext
+ */
+
+type ResourceDescriptor$1 = components['schemas']['ResourceDescriptor'];
+interface ListResourcesFilters {
+    search?: string;
+    archived?: boolean;
+}
+declare class ResourceContext {
+    /**
+     * Get resource metadata from view storage
+     */
+    static getResourceMetadata(resourceId: ResourceId, config: EnvironmentConfig): Promise<ResourceDescriptor$1 | null>;
+    /**
+     * List all resources by scanning view storage
+     */
+    static listResources(filters: ListResourcesFilters | undefined, config: EnvironmentConfig): Promise<ResourceDescriptor$1[]>;
+    /**
+     * Add content previews to resources (for search results)
+     * Retrieves and decodes the first 200 characters of each resource's primary representation
+     */
+    static addContentPreviews(resources: ResourceDescriptor$1[], config: EnvironmentConfig): Promise<Array<ResourceDescriptor$1 & {
+        content: string;
+    }>>;
+}
+
+/**
+ * Annotation Context
+ *
+ * Assembles annotation context from view storage and content store.
+ * Provides methods for:
+ * - Getting resource annotations
+ * - Building LLM context for annotations
+ * - Extracting annotation text context
+ * - Generating AI summaries
+ */
+
+type AnnotationLLMContextResponse = components['schemas']['AnnotationLLMContextResponse'];
+type Annotation$1 = components['schemas']['Annotation'];
+type AnnotationContextResponse = components['schemas']['AnnotationContextResponse'];
+type ContextualSummaryResponse = components['schemas']['ContextualSummaryResponse'];
+interface BuildContextOptions {
+    includeSourceContext?: boolean;
+    includeTargetContext?: boolean;
+    contextWindow?: number;
+}
+declare class AnnotationContext {
+    /**
+     * Build LLM context for an annotation
+     *
+     * @param annotationUri - Full annotation URI (e.g., http://localhost:4000/annotations/abc123)
+     * @param resourceId - Source resource ID
+     * @param config - Application configuration
+     * @param options - Context building options
+     * @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>;
+    /**
+     * Get resource annotations from view storage (fast path)
+     * Throws if view missing
+     */
+    static getResourceAnnotations(resourceId: ResourceId, config: EnvironmentConfig): Promise<ResourceAnnotations>;
+    /**
+     * Get all annotations
+     * @returns Array of all annotation objects
+     */
+    static getAllAnnotations(resourceId: ResourceId, config: EnvironmentConfig): Promise<Annotation$1[]>;
+    /**
+     * Enrich reference annotations with resolved document names
+     * Adds _resolvedDocumentName property to annotations that link to documents
+     * @private
+     */
+    private static enrichResolvedReferences;
+    /**
+     * Get resource stats (version info)
+     * @returns Version and timestamp info for the annotations
+     */
+    static getResourceStats(resourceId: ResourceId, config: EnvironmentConfig): Promise<{
+        resourceId: ResourceId;
+        version: number;
+        updatedAt: string;
+    }>;
+    /**
+     * Check if resource exists in view storage
+     */
+    static resourceExists(resourceId: ResourceId, config: EnvironmentConfig): Promise<boolean>;
+    /**
+     * Get a single annotation by ID
+     * O(1) lookup using resource ID to access view storage
+     */
+    static getAnnotation(annotationId: AnnotationId, resourceId: ResourceId, config: EnvironmentConfig): Promise<Annotation$1 | null>;
+    /**
+     * List annotations with optional filtering
+     * @param filters - Optional filters like resourceId and type
+     * @throws Error if resourceId not provided (cross-resource queries not supported in view storage)
+     */
+    static listAnnotations(filters: {
+        resourceId?: ResourceId;
+        type?: AnnotationCategory;
+    } | undefined, config: EnvironmentConfig): Promise<Annotation$1[]>;
+    /**
+     * Get annotation context (selected text with surrounding context)
+     */
+    static getAnnotationContext(annotationId: AnnotationId, resourceId: ResourceId, contextBefore: number, contextAfter: number, config: EnvironmentConfig): Promise<AnnotationContextResponse>;
+    /**
+     * Generate AI summary of annotation in context
+     */
+    static generateAnnotationSummary(annotationId: AnnotationId, resourceId: ResourceId, config: EnvironmentConfig): Promise<ContextualSummaryResponse>;
+    /**
+     * Get resource content as string
+     */
+    private static getResourceContent;
+    /**
+     * Extract annotation context from resource content
+     */
+    private static extractAnnotationContext;
+    /**
+     * Generate LLM summary of annotation in context
+     */
+    private static generateSummary;
+}
+
+/**
+ * Graph Context
+ *
+ * Provides graph database operations for resources and annotations.
+ * All methods require graph traversal - must use graph database.
+ */
+
+type Annotation = components['schemas']['Annotation'];
+type ResourceDescriptor = components['schemas']['ResourceDescriptor'];
+declare class GraphContext {
+    /**
+     * Get all resources referencing this resource (backlinks)
+     * Requires graph traversal - must use graph database
+     */
+    static getBacklinks(resourceId: ResourceId, config: EnvironmentConfig): Promise<Annotation[]>;
+    /**
+     * Find shortest path between two resources
+     * Requires graph traversal - must use graph database
+     */
+    static findPath(fromResourceId: ResourceId, toResourceId: ResourceId, config: EnvironmentConfig, maxDepth?: number): Promise<GraphPath[]>;
+    /**
+     * Get resource connections (graph edges)
+     * Requires graph traversal - must use graph database
+     */
+    static getResourceConnections(resourceId: ResourceId, config: EnvironmentConfig): Promise<GraphConnection[]>;
+    /**
+     * Search resources by name (cross-resource query)
+     * Requires full-text search - must use graph database
+     */
+    static searchResources(query: string, config: EnvironmentConfig, limit?: number): Promise<ResourceDescriptor[]>;
+}
+
+/**
+ * Annotation Detection
+ *
+ * Orchestrates the full annotation detection pipeline:
+ * 1. Fetch resource metadata and content
+ * 2. Build AI prompts using MotivationPrompts
+ * 3. Call AI inference
+ * 4. Parse and validate results using MotivationParsers
+ *
+ * This is the high-level API for AI-powered annotation detection.
+ * Workers and other consumers should use these methods instead of
+ * implementing detection logic directly.
+ */
+
+declare class AnnotationDetection {
+    /**
+     * Detect comments in a resource
+     *
+     * @param resourceId - The resource to analyze
+     * @param config - Environment configuration
+     * @param instructions - Optional user instructions for comment generation
+     * @param tone - Optional tone guidance (e.g., "academic", "conversational")
+     * @param density - Optional target number of comments per 2000 words
+     * @returns Array of validated comment matches
+     */
+    static detectComments(resourceId: ResourceId, config: EnvironmentConfig, instructions?: string, tone?: string, density?: number): Promise<CommentMatch[]>;
+    /**
+     * Detect highlights in a resource
+     *
+     * @param resourceId - The resource to analyze
+     * @param config - Environment configuration
+     * @param instructions - Optional user instructions for highlight selection
+     * @param density - Optional target number of highlights per 2000 words
+     * @returns Array of validated highlight matches
+     */
+    static detectHighlights(resourceId: ResourceId, config: EnvironmentConfig, instructions?: string, density?: number): Promise<HighlightMatch[]>;
+    /**
+     * Detect assessments in a resource
+     *
+     * @param resourceId - The resource to analyze
+     * @param config - Environment configuration
+     * @param instructions - Optional user instructions for assessment generation
+     * @param tone - Optional tone guidance (e.g., "critical", "supportive")
+     * @param density - Optional target number of assessments per 2000 words
+     * @returns Array of validated assessment matches
+     */
+    static detectAssessments(resourceId: ResourceId, config: EnvironmentConfig, instructions?: string, tone?: string, density?: number): Promise<AssessmentMatch[]>;
+    /**
+     * Detect tags in a resource for a specific category
+     *
+     * @param resourceId - The resource to analyze
+     * @param config - Environment configuration
+     * @param schemaId - The tag schema identifier (e.g., "irac", "imrad")
+     * @param category - The specific category to detect
+     * @returns Array of validated tag matches
+     */
+    static detectTags(resourceId: ResourceId, config: EnvironmentConfig, schemaId: string, category: string): Promise<TagMatch[]>;
+    /**
+     * Load resource content from representation store
+     * Helper method used by all detection methods
+     *
+     * @param resourceId - The resource ID to load
+     * @param config - Environment configuration
+     * @returns Resource content as string, or null if not available
+     */
+    private static loadResourceContent;
+}
+
+declare const PACKAGE_NAME = "@semiont/make-meaning";
+declare const VERSION = "0.1.0";
+
+export { AnnotationContext, AnnotationDetection, type BuildContextOptions, GraphContext, type ListResourcesFilters, PACKAGE_NAME, ResourceContext, VERSION };