harper-knowledge 0.1.0

package/dist/core/entries.js

@@ -0,0 +1,235 @@
+/**
+ * Knowledge Entry Management
+ *
+ * CRUD operations for knowledge base entries. Handles embedding generation,
+ * tag synchronization, and relationship management.
+ */
+import crypto from "node:crypto";
+import { generateEmbedding } from "./embeddings.js";
+import { syncTags } from "./tags.js";
+import { logEdit } from "./history.js";
+/**
+ * Strip embedding vectors from an entry to keep responses compact.
+ * Embeddings are large float arrays not useful in API responses.
+ */
+export function stripEmbedding(entry) {
+    const { embedding: _embedding, ...rest } = entry;
+    return rest;
+}
+/**
+ * Create a new knowledge entry.
+ *
+ * Generates an embedding from title + content, synchronizes tags,
+ * and stores the entry. A UUID is generated if no id is provided.
+ *
+ * @param data - Entry data to create
+ * @returns The created knowledge entry
+ */
+export async function createEntry(data) {
+    const id = data.id || crypto.randomUUID();
+    // Generate embedding from title + content
+    const embeddingText = `${data.title}\n\n${data.content}`;
+    let embedding;
+    try {
+        embedding = await generateEmbedding(embeddingText);
+    }
+    catch (error) {
+        logger?.warn?.("Failed to generate embedding for new entry:", error.message);
+    }
+    const entry = {
+        id,
+        title: data.title,
+        content: data.content,
+        tags: data.tags || [],
+        appliesTo: data.appliesTo,
+        source: data.source,
+        sourceUrl: data.sourceUrl,
+        confidence: data.confidence || "ai-generated",
+        addedBy: data.addedBy,
+        reviewedBy: data.reviewedBy,
+        customerContext: data.customerContext,
+        deprecated: data.deprecated ?? false,
+        embedding,
+    };
+    // Sync tag counts (no previous tags for new entries)
+    if (entry.tags.length > 0) {
+        await syncTags(entry.tags);
+    }
+    // Store the entry
+    await databases.kb.KnowledgeEntry.put(entry);
+    return entry;
+}
+/**
+ * Get a knowledge entry by ID.
+ *
+ * @param id - Entry ID
+ * @returns The entry, or null if not found
+ */
+export async function getEntry(id) {
+    const entry = await databases.kb.KnowledgeEntry.get(id);
+    return entry;
+}
+/**
+ * Update an existing knowledge entry.
+ *
+ * Merges the update data with the existing entry. If title or content changed,
+ * regenerates the embedding. Synchronizes tag counts if tags changed.
+ * Optionally logs the edit to the history table.
+ *
+ * @param id - ID of the entry to update
+ * @param data - Fields to update
+ * @param options - Optional edit tracking metadata
+ * @returns The updated entry
+ * @throws Error if the entry does not exist
+ */
+export async function updateEntry(id, data, options) {
+    const existing = await databases.kb.KnowledgeEntry.get(id);
+    if (!existing) {
+        throw new Error(`Knowledge entry not found: ${id}`);
+    }
+    const existingEntry = existing;
+    const previousTags = existingEntry.tags || [];
+    // Merge updates
+    const updated = {
+        ...existingEntry,
+        ...data,
+        id, // Ensure ID is never overwritten
+    };
+    // Regenerate embedding if title or content changed
+    const titleChanged = data.title !== undefined && data.title !== existingEntry.title;
+    const contentChanged = data.content !== undefined && data.content !== existingEntry.content;
+    if (titleChanged || contentChanged) {
+        const embeddingText = `${updated.title}\n\n${updated.content}`;
+        try {
+            updated.embedding = await generateEmbedding(embeddingText);
+        }
+        catch (error) {
+            logger?.warn?.("Failed to regenerate embedding for entry update:", error.message);
+        }
+    }
+    // Sync tag counts if tags changed
+    if (data.tags !== undefined) {
+        await syncTags(updated.tags, previousTags);
+    }
+    // Log the edit before overwriting
+    if (options?.editedBy) {
+        try {
+            await logEdit(id, existingEntry, updated, options.editedBy, options.editSummary);
+        }
+        catch (error) {
+            logger?.warn?.("Failed to log edit history:", error.message);
+        }
+    }
+    // Store the updated entry
+    await databases.kb.KnowledgeEntry.put(updated);
+    return updated;
+}
+/**
+ * Mark an entry as deprecated.
+ *
+ * @param id - ID of the entry to deprecate
+ * @throws Error if the entry does not exist
+ */
+export async function deprecateEntry(id) {
+    const existing = await databases.kb.KnowledgeEntry.get(id);
+    if (!existing) {
+        throw new Error(`Knowledge entry not found: ${id}`);
+    }
+    await databases.kb.KnowledgeEntry.put({
+        ...existing,
+        id,
+        deprecated: true,
+    });
+}
+/**
+ * Link a new entry as superseding an old entry.
+ *
+ * Sets newEntry.supersedesId = oldId and oldEntry.supersededById = newId.
+ *
+ * @param newId - ID of the new (superseding) entry
+ * @param oldId - ID of the old (superseded) entry
+ * @throws Error if either entry does not exist
+ */
+export async function linkSupersedes(newId, oldId) {
+    const newEntry = await databases.kb.KnowledgeEntry.get(newId);
+    const oldEntry = await databases.kb.KnowledgeEntry.get(oldId);
+    if (!newEntry) {
+        throw new Error(`New entry not found: ${newId}`);
+    }
+    if (!oldEntry) {
+        throw new Error(`Old entry not found: ${oldId}`);
+    }
+    await databases.kb.KnowledgeEntry.put({
+        ...newEntry,
+        id: newId,
+        supersedesId: oldId,
+    });
+    await databases.kb.KnowledgeEntry.put({
+        ...oldEntry,
+        id: oldId,
+        supersededById: newId,
+    });
+}
+/**
+ * Link multiple entries as siblings.
+ *
+ * For each entry, adds all other entry IDs to its siblingIds array (deduplicated).
+ *
+ * @param ids - IDs of entries to link as siblings
+ * @throws Error if any entry does not exist
+ */
+export async function linkSiblings(ids) {
+    if (ids.length < 2) {
+        return; // Need at least 2 entries to link
+    }
+    // Load all entries first to verify they exist
+    const entries = [];
+    for (const id of ids) {
+        const entry = await databases.kb.KnowledgeEntry.get(id);
+        if (!entry) {
+            throw new Error(`Entry not found: ${id}`);
+        }
+        entries.push(entry);
+    }
+    // Update each entry's siblingIds
+    for (let i = 0; i < ids.length; i++) {
+        const entry = entries[i];
+        const entryTyped = entry;
+        const existingSiblings = new Set(entryTyped.siblingIds || []);
+        // Add all other IDs (not itself)
+        for (const otherId of ids) {
+            if (otherId !== ids[i]) {
+                existingSiblings.add(otherId);
+            }
+        }
+        await databases.kb.KnowledgeEntry.put({
+            ...entry,
+            id: ids[i],
+            siblingIds: Array.from(existingSiblings),
+        });
+    }
+}
+/**
+ * Link two entries as related.
+ *
+ * Adds relatedId to the entry's relatedIds array (deduplicated).
+ * This is a one-directional link; call twice for bidirectional.
+ *
+ * @param id - ID of the entry to add a related link to
+ * @param relatedId - ID of the related entry
+ * @throws Error if the entry does not exist
+ */
+export async function linkRelated(id, relatedId) {
+    const entry = await databases.kb.KnowledgeEntry.get(id);
+    if (!entry) {
+        throw new Error(`Entry not found: ${id}`);
+    }
+    const entryTyped = entry;
+    const existingRelated = new Set(entryTyped.relatedIds || []);
+    existingRelated.add(relatedId);
+    await databases.kb.KnowledgeEntry.put({
+        ...entry,
+        id,
+        relatedIds: Array.from(existingRelated),
+    });
+}

package/dist/core/history.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Edit History Tracking
+ *
+ * Append-only audit log for knowledge entry edits.
+ * Records who changed what, when, and why — with a snapshot
+ * of the previous state for diffing.
+ */
+import type { KnowledgeEntry, KnowledgeEntryEdit } from "../types.ts";
+/**
+ * Log an edit to a knowledge entry.
+ *
+ * Compares the previous and updated entries to determine which fields changed,
+ * then stores an edit record with the previous snapshot.
+ *
+ * @param entryId - ID of the entry that was edited
+ * @param previous - The entry state before the edit
+ * @param updated - The entry state after the edit
+ * @param editedBy - Username of who made the edit
+ * @param editSummary - Optional description of what changed and why
+ * @returns The created edit record
+ */
+export declare function logEdit(entryId: string, previous: KnowledgeEntry, updated: KnowledgeEntry, editedBy: string, editSummary?: string): Promise<KnowledgeEntryEdit>;
+/**
+ * Get the edit history for a knowledge entry, newest first.
+ *
+ * @param entryId - ID of the entry to get history for
+ * @param limit - Maximum number of edits to return (default 50)
+ * @returns Array of edit records, newest first
+ */
+export declare function getHistory(entryId: string, limit?: number): Promise<KnowledgeEntryEdit[]>;

package/dist/core/history.js

@@ -0,0 +1,119 @@
+/**
+ * Edit History Tracking
+ *
+ * Append-only audit log for knowledge entry edits.
+ * Records who changed what, when, and why — with a snapshot
+ * of the previous state for diffing.
+ */
+import crypto from "node:crypto";
+/**
+ * Log an edit to a knowledge entry.
+ *
+ * Compares the previous and updated entries to determine which fields changed,
+ * then stores an edit record with the previous snapshot.
+ *
+ * @param entryId - ID of the entry that was edited
+ * @param previous - The entry state before the edit
+ * @param updated - The entry state after the edit
+ * @param editedBy - Username of who made the edit
+ * @param editSummary - Optional description of what changed and why
+ * @returns The created edit record
+ */
+export async function logEdit(entryId, previous, updated, editedBy, editSummary) {
+    // Determine which fields actually changed
+    const changedFields = detectChangedFields(previous, updated);
+    // Build a snapshot of only the previous values for changed fields
+    const previousSnapshot = {};
+    for (const field of changedFields) {
+        previousSnapshot[field] = previous[field];
+    }
+    const edit = {
+        id: crypto.randomUUID(),
+        entryId,
+        editedBy,
+        editSummary,
+        previousSnapshot,
+        changedFields,
+    };
+    await databases.kb.KnowledgeEntryEdit.put(edit);
+    return edit;
+}
+/**
+ * Get the edit history for a knowledge entry, newest first.
+ *
+ * @param entryId - ID of the entry to get history for
+ * @param limit - Maximum number of edits to return (default 50)
+ * @returns Array of edit records, newest first
+ */
+export async function getHistory(entryId, limit = 50) {
+    const edits = [];
+    for await (const record of databases.kb.KnowledgeEntryEdit.search({
+        conditions: [
+            { attribute: "entryId", comparator: "equals", value: entryId },
+        ],
+        sort: { attribute: "createdAt", descending: true },
+        limit,
+    })) {
+        edits.push(record);
+    }
+    return edits;
+}
+/**
+ * Compare two entry states and return the list of fields that differ.
+ * Ignores internal fields like embedding and updatedAt.
+ */
+function detectChangedFields(previous, updated) {
+    const trackableFields = [
+        "title",
+        "content",
+        "tags",
+        "appliesTo",
+        "source",
+        "sourceUrl",
+        "confidence",
+        "addedBy",
+        "reviewedBy",
+        "customerContext",
+        "deprecated",
+        "supersedesId",
+        "supersededById",
+        "siblingIds",
+        "relatedIds",
+    ];
+    const changed = [];
+    for (const field of trackableFields) {
+        const prev = previous[field];
+        const next = updated[field];
+        if (!deepEqual(prev, next)) {
+            changed.push(field);
+        }
+    }
+    return changed;
+}
+/**
+ * Simple deep equality check for JSON-serializable values.
+ */
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a == null || b == null)
+        return a === b;
+    if (typeof a !== typeof b)
+        return false;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        return a.every((val, i) => deepEqual(val, b[i]));
+    }
+    if (typeof a === "object" && typeof b === "object") {
+        const aObj = a;
+        const bObj = b;
+        const keys = new Set([...Object.keys(aObj), ...Object.keys(bObj)]);
+        for (const key of keys) {
+            if (!deepEqual(aObj[key], bObj[key]))
+                return false;
+        }
+        return true;
+    }
+    return false;
+}

package/dist/core/search.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Knowledge Base Search
+ *
+ * Supports keyword, semantic (vector), and hybrid search modes.
+ * Applies applicability context filtering to boost/demote results.
+ * Logs all queries to the QueryLog table for analytics.
+ */
+import type { SearchParams, SearchResult, ApplicabilityContext } from "../types.ts";
+/**
+ * Search the knowledge base.
+ *
+ * @param params - Search parameters including query, mode, tags, limit, context
+ * @returns Scored and sorted search results
+ */
+export declare function search(params: SearchParams): Promise<SearchResult[]>;
+/**
+ * Filter and re-score results based on applicability context.
+ *
+ * If the caller provides their environment context (Harper version, storage engine,
+ * Node version, platform), results that match get a score boost, while results
+ * that specify a different scope get a score penalty (but are NOT hidden).
+ */
+export declare function filterByApplicability(results: SearchResult[], context: ApplicabilityContext): SearchResult[];