@karmaniverous/jeeves-watcher 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -125,7 +125,7 @@ declare const jeevesWatcherConfigSchema: z.ZodObject<{
     }, z.core.$strip>>;
     extractors: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     stateDir: z.ZodOptional<z.ZodString>;
-    inferenceRules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    inferenceRules: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
         name: z.ZodString;
         description: z.ZodString;
         match: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -135,7 +135,7 @@ declare const jeevesWatcherConfigSchema: z.ZodObject<{
         }, z.core.$strip>]>>>;
         map: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<_karmaniverous_jsonmap.JsonMapMap, unknown, z.core.$ZodTypeInternals<_karmaniverous_jsonmap.JsonMapMap, unknown>>, z.ZodString]>>;
         template: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>>;
+    }, z.core.$strip>, z.ZodString]>>>;
     maps: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodType<_karmaniverous_jsonmap.JsonMapMap, unknown, z.core.$ZodTypeInternals<_karmaniverous_jsonmap.JsonMapMap, unknown>>, z.ZodString, z.ZodObject<{
         map: z.ZodUnion<[z.ZodType<_karmaniverous_jsonmap.JsonMapMap, unknown, z.core.$ZodTypeInternals<_karmaniverous_jsonmap.JsonMapMap, unknown>>, z.ZodString]>;
         description: z.ZodOptional<z.ZodString>;
@@ -162,6 +162,10 @@ declare const jeevesWatcherConfigSchema: z.ZodObject<{
             relevant: z.ZodNumber;
             noise: z.ZodNumber;
         }, z.core.$strip>>;
+        hybrid: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            textWeight: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
     logging: z.ZodOptional<z.ZodObject<{
         level: z.ZodOptional<z.ZodString>;
@@ -171,8 +175,18 @@ declare const jeevesWatcherConfigSchema: z.ZodObject<{
     maxRetries: z.ZodOptional<z.ZodNumber>;
     maxBackoffMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
-/** Top-level jeeves-watcher configuration: watch paths, embedding, vector store, rules, maps, API, and logging. */
-type JeevesWatcherConfig = z.infer<typeof jeevesWatcherConfigSchema>;
+/**
+ * Raw configuration as parsed from the Zod schema.
+ * May contain string file paths in `inferenceRules` that need resolution.
+ */
+type JeevesWatcherConfigInput = z.infer<typeof jeevesWatcherConfigSchema>;
+/**
+ * Resolved configuration with all file references loaded.
+ * After `loadConfig`, all string rule entries have been resolved to `InferenceRule` objects.
+ */
+type JeevesWatcherConfig = Omit<JeevesWatcherConfigInput, 'inferenceRules'> & {
+    inferenceRules?: InferenceRule[];
+};
 
 /**
  * @module config/schemas/services
@@ -389,7 +403,7 @@ declare function loadCustomHelpers(hbs: typeof Handlebars, helpers: Record<strin
  * The template engine: holds compiled templates and renders them against context.
  */
 declare class TemplateEngine {
-    private readonly hbs;
+    readonly hbs: typeof Handlebars;
     private readonly compiled;
     constructor(hbs: typeof Handlebars);
     /**
@@ -537,6 +551,23 @@ interface ApplyRulesResult {
     /** Names of rules that matched. */
     matchedRules: string[];
 }
+/**
+ * Optional parameters for applyRules beyond the required compiledRules and attributes.
+ */
+interface ApplyRulesOptions {
+    /** Optional record of named JsonMap definitions. */
+    namedMaps?: Record<string, JsonMapMap>;
+    /** Optional logger for warnings (falls back to console.warn). */
+    logger?: RuleLogger;
+    /** Optional template engine for rendering content templates. */
+    templateEngine?: TemplateEngine;
+    /** Optional config directory for resolving .json map file paths. */
+    configDir?: string;
+    /** Optional custom JsonMap transform library. */
+    customMapLib?: Record<string, (...args: unknown[]) => unknown>;
+    /** Optional global schemas collection for resolving schema references. */
+    globalSchemas?: Record<string, SchemaEntry>;
+}
 /**
  * Apply compiled inference rules to file attributes, returning merged metadata and optional rendered content.
  *
@@ -546,14 +577,10 @@ interface ApplyRulesResult {
  *
  * @param compiledRules - The compiled rules to evaluate.
  * @param attributes - The file attributes to match against.
- * @param namedMaps - Optional record of named JsonMap definitions.
- * @param logger - Optional logger for warnings (falls back to console.warn).
- * @param templateEngine - Optional template engine for rendering content templates.
- * @param configDir - Optional config directory for resolving .json map file paths.
- * @param globalSchemas - Optional global schemas collection for resolving schema references.
+ * @param options - Optional configuration for rule application.
  * @returns The merged metadata and optional rendered content.
  */
-declare function applyRules(compiledRules: CompiledRule[], attributes: FileAttributes, namedMaps?: Record<string, JsonMapMap>, logger?: RuleLogger, templateEngine?: TemplateEngine, configDir?: string, customMapLib?: Record<string, (...args: unknown[]) => unknown>, globalSchemas?: Record<string, SchemaEntry>): Promise<ApplyRulesResult>;
+declare function applyRules(compiledRules: CompiledRule[], attributes: FileAttributes, options?: ApplyRulesOptions): Promise<ApplyRulesResult>;
 
 /**
  * @module values/ValuesManager
@@ -689,6 +716,23 @@ interface VectorStore {
      * @yields Scrolled points.
      */
     scroll(filter?: Record<string, unknown>, limit?: number): AsyncGenerator<ScrolledPoint>;
+    /**
+     * Create a full-text payload index on the specified field.
+     *
+     * @param fieldName - The payload field to index.
+     */
+    ensureTextIndex(fieldName: string): Promise<void>;
+    /**
+     * Hybrid search combining dense vector and full-text match with RRF fusion.
+     *
+     * @param vector - The query vector.
+     * @param queryText - The raw query text for full-text matching.
+     * @param limit - Maximum results to return.
+     * @param textWeight - Weight for text results in RRF (0–1).
+     * @param filter - Optional Qdrant filter.
+     * @returns An array of search results.
+     */
+    hybridSearch(vector: number[], queryText: string, limit: number, textWeight: number, filter?: Record<string, unknown>): Promise<SearchResult[]>;
 }
 
 /**
@@ -701,6 +745,7 @@ declare class VectorStoreClient implements VectorStore {
     private readonly collectionName;
     private readonly dims;
     private readonly log;
+    private readonly pinoLogger?;
     /**
      * Create a new VectorStoreClient.
      *
@@ -756,21 +801,32 @@ declare class VectorStoreClient implements VectorStore {
      */
     getCollectionInfo(): Promise<CollectionInfo>;
     /**
-     * Sample points and discover payload field names and inferred types.
+     * Search for similar vectors.
+     *
+     * @param vector - The query vector.
+     * @param limit - Maximum results to return.
+     * @param filter - Optional Qdrant filter.
+     * @returns An array of search results.
+     */
+    search(vector: number[], limit: number, filter?: Record<string, unknown>, offset?: number): Promise<SearchResult[]>;
+    /**
+     * Create a full-text payload index on the specified field.
+     * Idempotent — skips if the field already has a text index.
      *
-     * @param target - Object to populate with discovered fields.
-     * @param sampleSize - Number of points to sample.
+     * @param fieldName - The payload field to index.
      */
-    private discoverPayloadFields;
+    ensureTextIndex(fieldName: string): Promise<void>;
     /**
-     * Search for similar vectors.
+     * Hybrid search combining dense vector and full-text match with RRF fusion.
      *
      * @param vector - The query vector.
+     * @param queryText - The raw query text for full-text matching.
      * @param limit - Maximum results to return.
+     * @param textWeight - Weight for text results in RRF (0–1).
      * @param filter - Optional Qdrant filter.
      * @returns An array of search results.
      */
-    search(vector: number[], limit: number, filter?: Record<string, unknown>, offset?: number): Promise<SearchResult[]>;
+    hybridSearch(vector: number[], queryText: string, limit: number, textWeight: number, filter?: Record<string, unknown>): Promise<SearchResult[]>;
     /**
      * Scroll through all points matching a filter.
      *
@@ -878,6 +934,14 @@ declare class DocumentProcessor implements DocumentProcessorInterface {
      * @param deps - The processor dependencies.
      */
     constructor({ config, embeddingProvider, vectorStore, compiledRules, logger, templateEngine, issuesManager, valuesManager, }: DocumentProcessorDeps);
+    /**
+     * Build merged metadata for a file and add matched_rules.
+     */
+    private buildMetadataWithRules;
+    /**
+     * Execute an async operation with standardized file error handling.
+     */
+    private withFileErrorHandling;
     /**
      * Process a file through the full pipeline: extract, hash, chunk, embed, upsert.
      *
@@ -995,6 +1059,54 @@ declare class EventQueue {
     private maybeResolveDrain;
 }
 
+/**
+ * @module rules/virtualRules
+ * In-memory virtual rule store for externally registered inference rules.
+ *
+ * Virtual rules are registered at runtime by external consumers (e.g., OpenClaw plugins)
+ * and merge into the inference pipeline alongside config-file rules.
+ * They survive config reloads but NOT service restarts.
+ */
+
+/**
+ * In-memory store for virtual inference rules.
+ *
+ * Virtual rules are appended AFTER config-file rules in evaluation order.
+ * Since inference uses last-match-wins for overlapping fields,
+ * virtual rules take precedence over config rules when both match the same file.
+ */
+declare class VirtualRuleStore {
+    private readonly entries;
+    /**
+     * Register virtual rules from an external source.
+     * Idempotent: re-registering with the same source replaces previous rules.
+     *
+     * @param source - Unique identifier for the rule source.
+     * @param rules - Inference rule definitions to register.
+     */
+    register(source: string, rules: InferenceRule[]): void;
+    /**
+     * Remove virtual rules by source.
+     *
+     * @param source - The source identifier to unregister.
+     * @returns true if rules were found and removed.
+     */
+    unregister(source: string): boolean;
+    /**
+     * Get all compiled virtual rules in registration order.
+     */
+    getCompiled(): CompiledRule[];
+    /**
+     * Get all raw virtual rule definitions grouped by source.
+     * Used by the merged virtual document.
+     */
+    getAll(): Record<string, InferenceRule[]>;
+    /** Check if any virtual rules are registered. */
+    get isEmpty(): boolean;
+    /** Total number of virtual rules across all sources. */
+    get size(): number;
+}
+
 /**
  * @module api/ReindexTracker
  * Tracks reindex operation state for status reporting. Single instance shared across handlers.
@@ -1054,6 +1166,8 @@ interface ApiServerOptions {
     configPath: string;
     /** Helper introspection for merged document. */
     helperIntrospection?: AllHelpersIntrospection;
+    /** Virtual rule store for externally registered inference rules. */
+    virtualRuleStore?: VirtualRuleStore;
 }
 /**
  * Create the Fastify API server with all routes registered.
@@ -1307,14 +1421,10 @@ declare class JeevesWatcher {
     private issuesManager;
     private valuesManager;
     private helperIntrospection;
-    /**
-     * Create a new JeevesWatcher instance.
-     *
-     * @param config - The application configuration.
-     * @param configPath - Optional config file path to watch for changes.
-     * @param factories - Optional component factories (for dependency injection).
-     * @param runtimeOptions - Optional runtime-only options (e.g., onFatalError).
-     */
+    private virtualRuleStore;
+    private vectorStore;
+    private embeddingProvider;
+    /** Create a new JeevesWatcher instance. */
     constructor(config: JeevesWatcherConfig, configPath?: string, factories?: Partial<JeevesWatcherFactories>, runtimeOptions?: JeevesWatcherRuntimeOptions);
     /**
      * Start the watcher, API server, and all components.