causantic 0.2.0

package/dist/clusters/hdbscan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hdbscan.d.ts","sourceRoot":"","sources":["../../src/clusters/hdbscan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EACb,YAAY,EACb,MAAM,oBAAoB,CAAC;AAQ5B;;;;;;;;;GASG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,KAAK,CAA6B;gBAE9B,OAAO,EAAE,cAAc;IAWnC;;OAEG;IACG,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC;IAIzD;;;OAGG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE;IAIzC;;OAEG;IACH,OAAO,CAAC,WAAW;IAyDnB;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAwFhC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAkB5B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAI5B;;OAEG;IACH,OAAO,CAAC,aAAa,EAAE,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE;IAkC5C;;OAEG;IACH,OAAO,CAAC,8BAA8B;IAuBtC;;OAEG;IACH,QAAQ,IAAI,YAAY,GAAG,IAAI;IAI/B;;OAEG;IACH,OAAO,CAAC,UAAU;CAgDnB;AAGD,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/clusters/hdbscan.js

@@ -0,0 +1,283 @@
+/**
+ * Native TypeScript HDBSCAN implementation.
+ * Replaces hdbscan-ts library with optimized implementation.
+ *
+ * Features:
+ * - Efficient data structures (Set, MinHeap, UnionFind)
+ * - Optional parallel core distance computation (worker_threads)
+ * - Both EOM and Leaf cluster extraction methods
+ * - Membership probabilities and outlier scores
+ * - Incremental point assignment (predict)
+ * - Optional KD-tree for approximate k-NN
+ */
+import { computeCoreDistances } from './hdbscan/core-distance.js';
+import { buildMST } from './hdbscan/mst.js';
+import { buildCondensedTreeWithMembers } from './hdbscan/hierarchy.js';
+import { euclideanDistance, angularDistance } from './hdbscan/kd-tree.js';
+import { computeCentroid, selectExemplars } from './hdbscan/incremental.js';
+/**
+ * HDBSCAN clustering algorithm.
+ *
+ * Usage:
+ * ```typescript
+ * const hdbscan = new HDBSCAN({ minClusterSize: 5 });
+ * const result = hdbscan.fit(embeddings);
+ * console.log(result.labels, result.numClusters);
+ * ```
+ */
+export class HDBSCAN {
+    options;
+    model = null;
+    constructor(options) {
+        this.options = {
+            minClusterSize: options.minClusterSize,
+            minSamples: options.minSamples ?? options.minClusterSize,
+            metric: options.metric ?? 'euclidean',
+            clusterSelectionMethod: options.clusterSelectionMethod ?? 'eom',
+            approximateKNN: options.approximateKNN ?? false,
+            parallel: options.parallel ?? true,
+        };
+    }
+    /**
+     * Fit HDBSCAN and return full result with probabilities and outlier scores.
+     */
+    async fit(embeddings) {
+        return this.fitInternal(embeddings);
+    }
+    /**
+     * Simple interface - just returns labels (drop-in for hdbscan-ts).
+     * This is synchronous for compatibility.
+     */
+    fitSync(embeddings) {
+        return this.fitInternal(embeddings).labels;
+    }
+    /**
+     * Internal fit method.
+     */
+    fitInternal(embeddings) {
+        const n = embeddings.length;
+        if (n === 0) {
+            return {
+                labels: [],
+                probabilities: [],
+                outlierScores: [],
+                numClusters: 0,
+                noiseCount: 0,
+            };
+        }
+        // Step 1: Compute core distances
+        const coreDistances = computeCoreDistances(embeddings, this.options.minSamples, this.options.metric, this.options.approximateKNN);
+        // Step 2: Build MST with mutual reachability distances
+        const mstEdges = buildMST(embeddings, coreDistances, this.options.metric);
+        // Step 3: Build condensed cluster tree with member tracking
+        const { tree, memberPoints } = buildCondensedTreeWithMembers(mstEdges, n, this.options.minClusterSize);
+        // Step 4: Extract clusters using specified method
+        const { selectedClusters, labels } = this.extractClustersAndLabels(tree, memberPoints, this.options.clusterSelectionMethod);
+        // Step 5: Compute probabilities and outlier scores
+        const probabilities = this.computeProbabilities(tree, labels, memberPoints, selectedClusters);
+        const outlierScores = this.computeOutlierScores(labels, probabilities);
+        // Build model for incremental assignment
+        this.buildModel(embeddings, coreDistances, labels, selectedClusters, memberPoints);
+        const numClusters = new Set(labels.filter((l) => l >= 0)).size;
+        const noiseCount = labels.filter((l) => l < 0).length;
+        return {
+            labels,
+            probabilities,
+            outlierScores,
+            numClusters,
+            noiseCount,
+        };
+    }
+    /**
+     * Extract clusters and assign labels.
+     */
+    extractClustersAndLabels(tree, memberPoints, method) {
+        const labels = new Array(tree.numPoints).fill(-1);
+        // Get all cluster nodes
+        const clusterNodes = [];
+        for (const [id, node] of tree.nodes) {
+            if (node.isCluster && id >= tree.numPoints) {
+                clusterNodes.push({
+                    id,
+                    children: node.children,
+                    lambdaBirth: node.lambdaBirth,
+                    lambdaDeath: node.lambdaDeath,
+                });
+            }
+        }
+        if (clusterNodes.length === 0) {
+            return { selectedClusters: [], labels };
+        }
+        // Compute stability for each cluster
+        const stability = new Map();
+        for (const cluster of clusterNodes) {
+            const points = memberPoints.get(cluster.id) ?? new Set();
+            const clusterDeath = isFinite(cluster.lambdaDeath) ? cluster.lambdaDeath : 0;
+            const persistence = cluster.lambdaBirth - clusterDeath;
+            stability.set(cluster.id, persistence > 0 ? points.size * persistence : 0);
+        }
+        let selectedClusters;
+        if (method === 'leaf') {
+            // Select leaf clusters (no children)
+            selectedClusters = clusterNodes
+                .filter((c) => c.children.length === 0)
+                .map((c) => c.id);
+        }
+        else {
+            // EOM: bottom-up selection
+            const sorted = [...clusterNodes].sort((a, b) => b.lambdaBirth - a.lambdaBirth);
+            const subtreeStability = new Map();
+            const selected = new Set();
+            for (const cluster of sorted) {
+                if (cluster.children.length === 0) {
+                    subtreeStability.set(cluster.id, stability.get(cluster.id) ?? 0);
+                    selected.add(cluster.id);
+                }
+                else {
+                    let childrenTotal = 0;
+                    for (const childId of cluster.children) {
+                        childrenTotal += subtreeStability.get(childId) ?? 0;
+                    }
+                    const ownStability = stability.get(cluster.id) ?? 0;
+                    if (ownStability >= childrenTotal) {
+                        subtreeStability.set(cluster.id, ownStability);
+                        selected.add(cluster.id);
+                        for (const childId of cluster.children) {
+                            selected.delete(childId);
+                        }
+                    }
+                    else {
+                        subtreeStability.set(cluster.id, childrenTotal);
+                    }
+                }
+            }
+            selectedClusters = Array.from(selected);
+        }
+        // Assign labels
+        for (let clusterLabel = 0; clusterLabel < selectedClusters.length; clusterLabel++) {
+            const clusterId = selectedClusters[clusterLabel];
+            const points = memberPoints.get(clusterId);
+            if (points) {
+                for (const pointId of points) {
+                    if (labels[pointId] === -1) {
+                        labels[pointId] = clusterLabel;
+                    }
+                }
+            }
+        }
+        return { selectedClusters, labels };
+    }
+    /**
+     * Compute membership probabilities.
+     */
+    computeProbabilities(tree, labels, memberPoints, selectedClusters) {
+        const probabilities = new Array(tree.numPoints).fill(0);
+        for (let i = 0; i < labels.length; i++) {
+            if (labels[i] >= 0) {
+                // Simple probability based on being in a cluster
+                probabilities[i] = 1.0;
+            }
+        }
+        return probabilities;
+    }
+    /**
+     * Compute outlier scores.
+     */
+    computeOutlierScores(labels, probabilities) {
+        return labels.map((label, i) => (label < 0 ? 1.0 : 1.0 - probabilities[i]));
+    }
+    /**
+     * Assign new points to existing clusters without reclustering.
+     */
+    predict(newEmbeddings) {
+        if (!this.model) {
+            throw new Error('Model not fitted. Call fit() first.');
+        }
+        const distFn = this.options.metric === 'euclidean' ? euclideanDistance : angularDistance;
+        const labels = new Array(newEmbeddings.length).fill(-1);
+        // Compute typical intra-cluster distances for threshold
+        const avgCentroidDistance = this.computeAverageCentroidDistance();
+        const threshold = avgCentroidDistance * 2; // Allow 2x the typical distance
+        for (let i = 0; i < newEmbeddings.length; i++) {
+            const point = newEmbeddings[i];
+            let bestLabel = -1;
+            let bestDistance = Infinity;
+            for (const [clusterLabel, centroid] of this.model.centroids) {
+                const dist = distFn(point, centroid);
+                if (dist < bestDistance) {
+                    bestDistance = dist;
+                    bestLabel = clusterLabel;
+                }
+            }
+            // Assign if within threshold
+            if (bestLabel !== -1 && bestDistance < threshold) {
+                labels[i] = bestLabel;
+            }
+        }
+        return labels;
+    }
+    /**
+     * Compute average distance from points to their cluster centroids.
+     */
+    computeAverageCentroidDistance() {
+        if (!this.model || this.model.centroids.size === 0) {
+            return 1.0;
+        }
+        const distFn = this.options.metric === 'euclidean' ? euclideanDistance : angularDistance;
+        let totalDist = 0;
+        let count = 0;
+        for (let i = 0; i < this.model.labels.length; i++) {
+            const label = this.model.labels[i];
+            if (label >= 0) {
+                const centroid = this.model.centroids.get(label);
+                if (centroid) {
+                    totalDist += distFn(this.model.embeddings[i], centroid);
+                    count++;
+                }
+            }
+        }
+        return count > 0 ? totalDist / count : 1.0;
+    }
+    /**
+     * Get the fitted model for persistence.
+     */
+    getModel() {
+        return this.model;
+    }
+    /**
+     * Build model from clustering result.
+     */
+    buildModel(embeddings, coreDistances, labels, selectedClusters, memberPoints) {
+        const centroids = new Map();
+        const exemplars = new Map();
+        // Group points by cluster label
+        const clusterPoints = new Map();
+        for (let i = 0; i < labels.length; i++) {
+            const label = labels[i];
+            if (label >= 0) {
+                if (!clusterPoints.has(label)) {
+                    clusterPoints.set(label, []);
+                }
+                clusterPoints.get(label).push(i);
+            }
+        }
+        // Compute centroids and exemplars
+        for (const [label, pointIndices] of clusterPoints) {
+            const points = pointIndices.map((i) => embeddings[i]);
+            const centroid = computeCentroid(points);
+            centroids.set(label, centroid);
+            const clusterExemplars = selectExemplars(pointIndices, embeddings, centroid, 3, this.options.metric);
+            exemplars.set(label, clusterExemplars);
+        }
+        this.model = {
+            embeddings,
+            coreDistances,
+            labels,
+            centroids,
+            exemplars,
+            lambdaValues: new Array(embeddings.length).fill(0),
+            clusterMaxLambda: new Map(),
+        };
+    }
+}
+//# sourceMappingURL=hdbscan.js.map

package/dist/clusters/hdbscan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hdbscan.js","sourceRoot":"","sources":["../../src/clusters/hdbscan.ts"],"names":[],"mappings":"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"}

package/dist/clusters/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Cluster management exports.
+ */
+export { ClusterManager, clusterManager } from './cluster-manager.js';
+export type { ClusteringResult, ClusteringOptions } from './cluster-manager.js';
+export { ClusterRefresher, clusterRefresher } from './cluster-refresh.js';
+export type { RefreshResult, RefreshOptions } from './cluster-refresh.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/clusters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/clusters/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtE,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAGhF,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC1E,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/clusters/index.js

@@ -0,0 +1,8 @@
+/**
+ * Cluster management exports.
+ */
+// Cluster manager
+export { ClusterManager, clusterManager } from './cluster-manager.js';
+// Cluster refresh
+export { ClusterRefresher, clusterRefresher } from './cluster-refresh.js';
+//# sourceMappingURL=index.js.map

package/dist/clusters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/clusters/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,kBAAkB;AAClB,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGtE,kBAAkB;AAClB,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/config/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Configuration module exports.
+ */
+export * from './memory-config.js';
+export * from './loader.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC"}

package/dist/config/index.js

@@ -0,0 +1,6 @@
+/**
+ * Configuration module exports.
+ */
+export * from './memory-config.js';
+export * from './loader.js';
+//# sourceMappingURL=index.js.map

package/dist/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC"}

package/dist/config/loader.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Configuration loader with priority-based resolution.
+ *
+ * Priority (highest to lowest):
+ * 1. CLI flags (passed directly)
+ * 2. Environment variables (CAUSANTIC_*)
+ * 3. Project config file (./causantic.config.json)
+ * 4. User config file (~/.causantic/config.json)
+ * 5. Built-in defaults
+ */
+/** External config file structure (matches config.schema.json) */
+export interface ExternalConfig {
+    decay?: {
+        backward?: {
+            type?: 'linear' | 'exponential' | 'delayed-linear';
+            diesAtHops?: number;
+            holdHops?: number;
+        };
+        forward?: {
+            type?: 'linear' | 'exponential' | 'delayed-linear';
+            diesAtHops?: number;
+            holdHops?: number;
+        };
+    };
+    clustering?: {
+        threshold?: number;
+        minClusterSize?: number;
+    };
+    traversal?: {
+        maxDepth?: number;
+        minWeight?: number;
+        directHitBoost?: number;
+        graphAgreementBoost?: number;
+    };
+    tokens?: {
+        claudeMdBudget?: number;
+        mcpMaxResponse?: number;
+    };
+    storage?: {
+        dbPath?: string;
+        vectorPath?: string;
+    };
+    llm?: {
+        clusterRefreshModel?: string;
+        refreshRateLimitPerMin?: number;
+    };
+    encryption?: {
+        enabled?: boolean;
+        cipher?: 'chacha20' | 'sqlcipher';
+        keySource?: 'keychain' | 'env' | 'prompt';
+        auditLog?: boolean;
+    };
+    vectors?: {
+        /** TTL in days for vectors. Vectors accessed within this period are kept. Default: 90 */
+        ttlDays?: number;
+    };
+    embedding?: {
+        /** Device for embedding inference: 'auto' | 'coreml' | 'cuda' | 'cpu' | 'wasm'. Default: 'auto'. */
+        device?: string;
+    };
+    maintenance?: {
+        /** Hour of day (0-23) to run reclustering. Default: 2. */
+        clusterHour?: number;
+    };
+}
+/** Default external config values */
+declare const EXTERNAL_DEFAULTS: Required<ExternalConfig>;
+/**
+ * Validate the external config structure.
+ */
+export declare function validateExternalConfig(config: ExternalConfig): string[];
+export interface LoadConfigOptions {
+    /** CLI overrides (highest priority) */
+    cliOverrides?: Partial<ExternalConfig>;
+    /** Skip loading environment variables */
+    skipEnv?: boolean;
+    /** Skip loading project config file */
+    skipProjectConfig?: boolean;
+    /** Skip loading user config file */
+    skipUserConfig?: boolean;
+    /** Custom project config path */
+    projectConfigPath?: string;
+    /** Custom user config path */
+    userConfigPath?: string;
+}
+/**
+ * Load configuration with priority-based resolution.
+ *
+ * Priority (highest to lowest):
+ * 1. CLI flags (cliOverrides)
+ * 2. Environment variables (CAUSANTIC_*)
+ * 3. Project config file (./causantic.config.json)
+ * 4. User config file (~/.causantic/config.json)
+ * 5. Built-in defaults
+ */
+export declare function loadConfig(options?: LoadConfigOptions): Required<ExternalConfig>;
+/**
+ * Get the resolved storage paths.
+ */
+export declare function getResolvedPaths(config: Required<ExternalConfig>): {
+    dbPath: string;
+    vectorPath: string;
+};
+export { EXTERNAL_DEFAULTS };
+//# sourceMappingURL=loader.d.ts.map

package/dist/config/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"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"}