network-ai 5.10.1 → 5.11.0

package/dist/esm/lib/quadtree.js

@@ -0,0 +1,259 @@
+"use strict";
+/**
+ * Barnes-Hut QuadTree — Spatial indexing for O(n log n) force simulation
+ *
+ * Used by the topology dashboard to replace the naive O(n²) all-pairs
+ * repulsion with Barnes-Hut approximation. Also provides viewport queries
+ * for culling off-screen nodes.
+ *
+ * @module QuadTree
+ * @version 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuadTree = void 0;
+// ============================================================================
+// QUADTREE NODE
+// ============================================================================
+const QT_CAPACITY = 8; // Points per leaf before subdividing
+/**
+ * A QuadTree for 2D spatial indexing with Barnes-Hut mass summaries.
+ *
+ * Usage:
+ * ```typescript
+ * const qt = new QuadTree({ x: 500, y: 400, halfW: 500, halfH: 400 });
+ * qt.insert({ id: 'a', x: 100, y: 200 });
+ * qt.insert({ id: 'b', x: 300, y: 150 });
+ *
+ * // Barnes-Hut force query (theta = 0.5)
+ * qt.forceOnPoint(100, 200, 0.5, (cx, cy, mass, dx, dy, distSq) => {
+ *   // Apply repulsion force from (cx, cy) with given mass
+ * });
+ *
+ * // Viewport query
+ * const visible = qt.queryRange({ x: 250, y: 250, halfW: 250, halfH: 250 });
+ * ```
+ */
+class QuadTree {
+    bounds;
+    points = [];
+    divided = false;
+    nw = null;
+    ne = null;
+    sw = null;
+    se = null;
+    mass = { count: 0, cx: 0, cy: 0 };
+    constructor(bounds) {
+        this.bounds = bounds;
+    }
+    // --------------------------------------------------------------------------
+    // INSERTION
+    // --------------------------------------------------------------------------
+    /**
+     * Insert a point into the tree.
+     * @returns true if inserted, false if out of bounds
+     */
+    insert(point) {
+        if (!this.containsPoint(point.x, point.y))
+            return false;
+        // Update mass center incrementally
+        const prev = this.mass.count;
+        this.mass.cx = (this.mass.cx * prev + point.x) / (prev + 1);
+        this.mass.cy = (this.mass.cy * prev + point.y) / (prev + 1);
+        this.mass.count = prev + 1;
+        if (!this.divided && this.points.length < QT_CAPACITY) {
+            this.points.push(point);
+            return true;
+        }
+        if (!this.divided) {
+            this.subdivide();
+        }
+        if (this.nw.insert(point))
+            return true;
+        if (this.ne.insert(point))
+            return true;
+        if (this.sw.insert(point))
+            return true;
+        if (this.se.insert(point))
+            return true;
+        // Shouldn't happen if containsPoint passed, but safety fallback
+        return false;
+    }
+    /**
+     * Build the tree from an array of points (faster than individual inserts).
+     */
+    static build(points, bounds) {
+        const tree = new QuadTree(bounds);
+        for (const p of points) {
+            tree.insert(p);
+        }
+        return tree;
+    }
+    // --------------------------------------------------------------------------
+    // QUERIES
+    // --------------------------------------------------------------------------
+    /**
+     * Find all points within a rectangular viewport.
+     */
+    queryRange(range) {
+        const found = [];
+        this.queryRangeInto(range, found);
+        return found;
+    }
+    queryRangeInto(range, found) {
+        if (!this.intersects(range))
+            return;
+        for (const p of this.points) {
+            if (p.x >= range.x - range.halfW &&
+                p.x <= range.x + range.halfW &&
+                p.y >= range.y - range.halfH &&
+                p.y <= range.y + range.halfH) {
+                found.push(p);
+            }
+        }
+        if (this.divided) {
+            this.nw.queryRangeInto(range, found);
+            this.ne.queryRangeInto(range, found);
+            this.sw.queryRangeInto(range, found);
+            this.se.queryRangeInto(range, found);
+        }
+    }
+    // --------------------------------------------------------------------------
+    // BARNES-HUT FORCE TRAVERSAL
+    // --------------------------------------------------------------------------
+    /**
+     * Traverse the tree with Barnes-Hut approximation for a single point.
+     *
+     * For each region, if the region is "far enough" (width/distance < theta),
+     * treat it as a point mass at the center of mass. Otherwise recurse.
+     *
+     * @param px - Query point x
+     * @param py - Query point y
+     * @param theta - Opening angle threshold (0.5 is common, higher = faster but less accurate)
+     * @param callback - Called for each mass interaction: (cx, cy, mass, dx, dy, distSq)
+     */
+    forceOnPoint(px, py, theta, callback) {
+        if (this.mass.count === 0)
+            return;
+        const dx = this.mass.cx - px;
+        const dy = this.mass.cy - py;
+        const distSq = dx * dx + dy * dy;
+        // If this is a leaf with points, interact directly
+        if (!this.divided) {
+            if (distSq > 0.01) {
+                callback(this.mass.cx, this.mass.cy, this.mass.count, dx, dy, distSq);
+            }
+            return;
+        }
+        // Barnes-Hut criterion: region width / distance < theta → approximate
+        const regionWidth = this.bounds.halfW * 2;
+        if (regionWidth * regionWidth < theta * theta * distSq) {
+            callback(this.mass.cx, this.mass.cy, this.mass.count, dx, dy, distSq);
+            return;
+        }
+        // Recurse into children
+        this.nw.forceOnPoint(px, py, theta, callback);
+        this.ne.forceOnPoint(px, py, theta, callback);
+        this.sw.forceOnPoint(px, py, theta, callback);
+        this.se.forceOnPoint(px, py, theta, callback);
+    }
+    // --------------------------------------------------------------------------
+    // ACCESSORS
+    // --------------------------------------------------------------------------
+    /** Total point count in this subtree */
+    get count() {
+        return this.mass.count;
+    }
+    /** The mass summary of this subtree */
+    getMass() {
+        return { ...this.mass };
+    }
+    /** The bounds of this node */
+    getBounds() {
+        return { ...this.bounds };
+    }
+    /** Whether this node has been subdivided */
+    get isSubdivided() {
+        return this.divided;
+    }
+    // --------------------------------------------------------------------------
+    // CLUSTERING SUPPORT
+    // --------------------------------------------------------------------------
+    /**
+     * Get cluster summaries at a given depth or size threshold.
+     * Returns groups of points that share a QuadTree cell below the given size.
+     *
+     * @param maxCellSize - Maximum cell width to stop recursing (in world units)
+     * @returns Array of clusters, each with center, count, and contained point ids
+     */
+    getClusters(maxCellSize) {
+        const clusters = [];
+        this.collectClusters(maxCellSize, clusters);
+        return clusters;
+    }
+    collectClusters(maxCellSize, out) {
+        if (this.mass.count === 0)
+            return;
+        const cellSize = this.bounds.halfW * 2;
+        // If this cell is small enough OR is a leaf, emit as cluster
+        if (cellSize <= maxCellSize || !this.divided) {
+            const ids = this.collectAllIds();
+            if (ids.length > 0) {
+                out.push({
+                    cx: this.mass.cx,
+                    cy: this.mass.cy,
+                    count: this.mass.count,
+                    ids,
+                });
+            }
+            return;
+        }
+        this.nw.collectClusters(maxCellSize, out);
+        this.ne.collectClusters(maxCellSize, out);
+        this.sw.collectClusters(maxCellSize, out);
+        this.se.collectClusters(maxCellSize, out);
+    }
+    collectAllIds() {
+        const ids = [];
+        for (const p of this.points)
+            ids.push(p.id);
+        if (this.divided) {
+            ids.push(...this.nw.collectAllIds());
+            ids.push(...this.ne.collectAllIds());
+            ids.push(...this.sw.collectAllIds());
+            ids.push(...this.se.collectAllIds());
+        }
+        return ids;
+    }
+    // --------------------------------------------------------------------------
+    // INTERNALS
+    // --------------------------------------------------------------------------
+    subdivide() {
+        const { x, y, halfW, halfH } = this.bounds;
+        const qW = halfW / 2;
+        const qH = halfH / 2;
+        this.nw = new QuadTree({ x: x - qW, y: y - qH, halfW: qW, halfH: qH });
+        this.ne = new QuadTree({ x: x + qW, y: y - qH, halfW: qW, halfH: qH });
+        this.sw = new QuadTree({ x: x - qW, y: y + qH, halfW: qW, halfH: qH });
+        this.se = new QuadTree({ x: x + qW, y: y + qH, halfW: qW, halfH: qH });
+        // Re-insert existing points into children
+        for (const p of this.points) {
+            this.nw.insert(p) || this.ne.insert(p) || this.sw.insert(p) || this.se.insert(p);
+        }
+        this.points = [];
+        this.divided = true;
+    }
+    containsPoint(x, y) {
+        return (x >= this.bounds.x - this.bounds.halfW &&
+            x <= this.bounds.x + this.bounds.halfW &&
+            y >= this.bounds.y - this.bounds.halfH &&
+            y <= this.bounds.y + this.bounds.halfH);
+    }
+    intersects(range) {
+        return !(range.x - range.halfW > this.bounds.x + this.bounds.halfW ||
+            range.x + range.halfW < this.bounds.x - this.bounds.halfW ||
+            range.y - range.halfH > this.bounds.y + this.bounds.halfH ||
+            range.y + range.halfH < this.bounds.y - this.bounds.halfH);
+    }
+}
+exports.QuadTree = QuadTree;
+//# sourceMappingURL=quadtree.js.map

package/dist/esm/lib/quadtree.js.map

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

package/dist/esm/lib/route-classifier.js

@@ -0,0 +1,217 @@
+"use strict";
+/**
+ * Route Classifier — Short-Circuit Routing for Network-AI
+ *
+ * Classifies an incoming goal into one of three categories before any
+ * DAG planning occurs. Simple factual lookups are routed directly to a
+ * single agent, bypassing the Blackboard/locking layer entirely to save
+ * latency and token cost. Complex synthesis uses the full DAG pipeline.
+ * System failures are surfaced immediately.
+ *
+ * Zero external dependencies — the classifier function is pluggable so
+ * callers can use any model (Haiku, Llama-3-8B, rule-based heuristic, …).
+ *
+ * @module RouteClassifier
+ * @version 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RouteClassifier = void 0;
+exports.createHeuristicClassifier = createHeuristicClassifier;
+exports.createLLMClassifier = createLLMClassifier;
+// ============================================================================
+// RULE-BASED HEURISTIC CLASSIFIER (built-in, zero model cost)
+// ============================================================================
+/**
+ * A simple keyword / length heuristic classifier for when you don't want to
+ * spend tokens on a model call for every request.
+ *
+ * Treats goals of ≤ 15 words with question-like phrasing as FACTUAL_LOOKUP
+ * and everything else as COMPLEX_SYNTHESIS.
+ */
+function createHeuristicClassifier() {
+    const LOOKUP_STARTERS = [
+        'what is', 'what are', 'who is', 'who are', 'when is', 'when was',
+        'where is', 'where was', 'how many', 'how much', 'define ', 'list ',
+        'name ', 'tell me', 'give me', 'show me',
+    ];
+    return async (goal) => {
+        const normalized = goal.trim().toLowerCase();
+        if (!normalized) {
+            return {
+                category: 'SYSTEM_FAILURE',
+                rationale: 'Goal is empty',
+                confidence: 1,
+                classifiedAt: Date.now(),
+            };
+        }
+        const wordCount = normalized.split(/\s+/).length;
+        const isShort = wordCount <= 15;
+        const startsLikeQuestion = LOOKUP_STARTERS.some((s) => normalized.startsWith(s));
+        const endsWithQuestion = normalized.endsWith('?');
+        if (isShort && (startsLikeQuestion || endsWithQuestion)) {
+            return {
+                category: 'FACTUAL_LOOKUP',
+                rationale: `Short goal (${wordCount} words) with question-like phrasing.`,
+                confidence: 0.8,
+                classifiedAt: Date.now(),
+            };
+        }
+        return {
+            category: 'COMPLEX_SYNTHESIS',
+            rationale: `Goal requires multi-step reasoning (${wordCount} words).`,
+            confidence: 0.75,
+            classifiedAt: Date.now(),
+        };
+    };
+}
+/**
+ * Build a classifier backed by an LLM via the Network-AI executor API.
+ *
+ * @param executor - The executor function from the adapter system
+ * @param classifierAgentId - Agent ID for the fast classification model
+ */
+function createLLMClassifier(executor, classifierAgentId) {
+    return async (goal) => {
+        const prompt = [
+            'Classify the following goal into exactly one category:',
+            '  FACTUAL_LOOKUP    — simple factual question answerable in one step',
+            '  COMPLEX_SYNTHESIS — requires multi-step research/reasoning/execution',
+            '  SYSTEM_FAILURE    — invalid, malformed, or unclassifiable input',
+            '',
+            `GOAL: ${goal}`,
+            '',
+            'Respond with ONLY valid JSON matching this schema:',
+            '{"category":"FACTUAL_LOOKUP|COMPLEX_SYNTHESIS|SYSTEM_FAILURE","rationale":"...","confidence":0.0-1.0}',
+        ].join('\n');
+        try {
+            const result = await executor(classifierAgentId, { action: 'classify', params: { prompt } }, { agentId: classifierAgentId, taskId: `classify-${Date.now()}`, metadata: { type: 'route-classification' } });
+            if (!result.success || !result.data) {
+                return {
+                    category: 'COMPLEX_SYNTHESIS',
+                    rationale: 'Classifier returned no data — defaulting to COMPLEX_SYNTHESIS',
+                    confidence: 0.5,
+                    classifiedAt: Date.now(),
+                };
+            }
+            // Parse response
+            let parsed;
+            const raw = typeof result.data === 'string' ? result.data : JSON.stringify(result.data);
+            try {
+                // Strip markdown fences
+                const cleaned = raw.replace(/```[a-z]*\n?/g, '').replace(/```/g, '').trim();
+                const start = cleaned.indexOf('{');
+                const end = cleaned.lastIndexOf('}');
+                parsed = JSON.parse(cleaned.substring(start, end + 1));
+            }
+            catch {
+                return {
+                    category: 'COMPLEX_SYNTHESIS',
+                    rationale: 'Classifier response parse failed — defaulting to COMPLEX_SYNTHESIS',
+                    confidence: 0.4,
+                    classifiedAt: Date.now(),
+                };
+            }
+            const validCategories = ['FACTUAL_LOOKUP', 'COMPLEX_SYNTHESIS', 'SYSTEM_FAILURE'];
+            const category = validCategories.includes(parsed.category) ? parsed.category : 'COMPLEX_SYNTHESIS';
+            return {
+                category,
+                rationale: parsed.rationale ?? '',
+                confidence: typeof parsed.confidence === 'number' ? Math.min(1, Math.max(0, parsed.confidence)) : undefined,
+                classifiedAt: Date.now(),
+            };
+        }
+        catch (err) {
+            return {
+                category: 'COMPLEX_SYNTHESIS',
+                rationale: `Classifier error (${err.message}) — defaulting to COMPLEX_SYNTHESIS`,
+                confidence: 0.3,
+                classifiedAt: Date.now(),
+            };
+        }
+    };
+}
+// ============================================================================
+// ROUTE CLASSIFIER
+// ============================================================================
+/**
+ * RouteClassifier evaluates a goal before DAG planning begins and decides
+ * whether to short-circuit to a single agent (FACTUAL_LOOKUP) or proceed
+ * with the full multi-agent pipeline (COMPLEX_SYNTHESIS).
+ *
+ * @example
+ * ```typescript
+ * const classifier = new RouteClassifier(createHeuristicClassifier());
+ * const { category } = await classifier.classify('What is the capital of France?');
+ * // category === 'FACTUAL_LOOKUP'
+ * ```
+ */
+class RouteClassifier {
+    classifierFn;
+    options;
+    constructor(classifierFn, options = {}) {
+        this.classifierFn = classifierFn;
+        this.options = options;
+    }
+    /**
+     * Classify a goal.
+     */
+    async classify(goal) {
+        if (!goal || typeof goal !== 'string') {
+            return {
+                category: 'SYSTEM_FAILURE',
+                rationale: 'Goal must be a non-empty string',
+                confidence: 1,
+                classifiedAt: Date.now(),
+            };
+        }
+        return this.classifierFn(goal);
+    }
+    /**
+     * Classify a goal and, if FACTUAL_LOOKUP, short-circuit to a single agent.
+     *
+     * Returns the classification result and, when short-circuited, the agent's
+     * direct answer. The caller should check `result.shortCircuited` — if false,
+     * proceed with the normal DAG pipeline.
+     *
+     * @param goal - Natural language goal
+     * @param executor - Agent executor (required for FACTUAL_LOOKUP short-circuit)
+     * @param fallbackAgentId - Agent to call on FACTUAL_LOOKUP (overrides options.lookupAgentId)
+     */
+    async route(goal, executor, fallbackAgentId) {
+        const classification = await this.classify(goal);
+        if (classification.category === 'SYSTEM_FAILURE') {
+            return {
+                classification,
+                shortCircuited: true,
+                error: `System failure: ${classification.rationale}`,
+            };
+        }
+        if (classification.category === 'FACTUAL_LOOKUP') {
+            const agentId = fallbackAgentId ?? this.options.lookupAgentId;
+            if (!executor || !agentId) {
+                // No executor configured — fall through to DAG pipeline
+                return { classification, shortCircuited: false };
+            }
+            try {
+                const result = await executor(agentId, { action: 'answer', params: { goal } }, { agentId, taskId: `lookup-${Date.now()}`, metadata: { type: 'factual-lookup' } });
+                return {
+                    classification,
+                    shortCircuited: true,
+                    answer: result.data,
+                    error: result.success ? undefined : result.error?.message,
+                };
+            }
+            catch (err) {
+                return {
+                    classification,
+                    shortCircuited: true,
+                    error: err.message,
+                };
+            }
+        }
+        // COMPLEX_SYNTHESIS — proceed with DAG
+        return { classification, shortCircuited: false };
+    }
+}
+exports.RouteClassifier = RouteClassifier;
+//# sourceMappingURL=route-classifier.js.map

package/dist/esm/lib/route-classifier.js.map

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