sxng-cli 1.0.9 → 1.1.0

package/dist/deep/co-occurrence.js

@@ -0,0 +1,95 @@
+/**
+ * Co-occurrence matrix and cross-results frequency statistics.
+ *
+ * Co-occurrence: word pairs that appear within the same result.
+ * Frequency: how many results contain each term.
+ * Both derived from TF-IDF tokenization output.
+ */
+import { tokenize } from './tfidf.js';
+import { getEntityDegree } from './degree-utils.js';
+const MAX_TERMS_FOR_CO_OCCURRENCE = 50;
+const DEFAULT_THRESHOLD = 2;
+/** Build co-occurrence matrix from results.
+ *  Only results with `content` are processed.
+ *  If unique terms > maxTerms, take the top by frequency and set truncated=true.
+ */
+export function buildCoOccurrence(results, opts) {
+    const threshold = opts?.threshold ?? DEFAULT_THRESHOLD;
+    const maxTerms = opts?.maxTerms ?? MAX_TERMS_FOR_CO_OCCURRENCE;
+    const withContent = results.filter(r => r.content);
+    // Per-result term sets
+    const perResultTermSets = [];
+    const globalFreq = new Map(); // term → # results containing it
+    for (const result of withContent) {
+        const text = `${result.title || ''} ${result.content || ''}`;
+        const tokens = tokenize(text);
+        const termSet = new Set(tokens);
+        perResultTermSets.push(termSet);
+        for (const term of termSet) {
+            globalFreq.set(term, (globalFreq.get(term) || 0) + 1);
+        }
+    }
+    // Truncate to top maxTerms by frequency
+    const sortedTerms = Array.from(globalFreq.entries())
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, maxTerms)
+        .map(([term]) => term);
+    const truncated = globalFreq.size > maxTerms;
+    const termIndex = new Set(sortedTerms);
+    // Count co-occurrences
+    const pairCounts = new Map();
+    for (const termSet of perResultTermSets) {
+        const filtered = sortedTerms.filter(t => termSet.has(t));
+        for (let i = 0; i < filtered.length; i++) {
+            for (let j = i + 1; j < filtered.length; j++) {
+                const key = filtered[i] < filtered[j]
+                    ? `${filtered[i]}|${filtered[j]}`
+                    : `${filtered[j]}|${filtered[i]}`;
+                pairCounts.set(key, (pairCounts.get(key) || 0) + 1);
+            }
+        }
+    }
+    const pairs = [];
+    for (const [key, count] of pairCounts) {
+        if (count >= threshold) {
+            const [term1, term2] = key.split('|');
+            pairs.push({ term1, term2, count });
+        }
+    }
+    pairs.sort((a, b) => b.count - a.count);
+    return { pairs, truncated, maxTerms };
+}
+/** Count how many results contain each term. */
+export function computeCrossResultFrequency(results, opts) {
+    const top = opts?.top ?? 50;
+    const withContent = results.filter(r => r.content);
+    const freq = new Map();
+    for (const result of withContent) {
+        const text = `${result.title || ''} ${result.content || ''}`;
+        const tokens = tokenize(text);
+        const seen = new Set(tokens);
+        for (const term of seen) {
+            freq.set(term, (freq.get(term) || 0) + 1);
+        }
+    }
+    return Array.from(freq.entries())
+        .map(([term, count]) => ({ term, count }))
+        .sort((a, b) => b.count - a.count)
+        .slice(0, top);
+}
+/** Get existing entity nodes from the graph with their on-demand degree. */
+export function getExistingEntityContext(graph) {
+    const entities = [];
+    graph.forEachNode((node, attrs) => {
+        if (attrs.type === 'entity') {
+            entities.push({
+                id: node,
+                label: attrs.label,
+                degree: getEntityDegree(graph, node),
+                entityType: attrs.entityType,
+            });
+        }
+    });
+    return entities.sort((a, b) => b.degree - a.degree);
+}
+//# sourceMappingURL=co-occurrence.js.map

package/dist/deep/co-occurrence.js.map

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

package/dist/deep/degree-utils.d.ts

@@ -0,0 +1,39 @@
+/**
+ * On-demand degree computation for entity nodes.
+ *
+ * Degree is NOT stored in node attributes — it's computed on-the-fly
+ * from the graph topology using graphology's O(1) inDegree/outDegree.
+ * This ensures degree is always consistent with the current graph state.
+ */
+import { DirectedGraph } from 'graphology';
+import { GraphNodeAttrs, GraphEdgeAttrs } from './graph.js';
+/** Get the total degree (in + out) for a single node. O(1) via graphology. */
+export declare function getEntityDegree(graph: DirectedGraph<GraphNodeAttrs, GraphEdgeAttrs>, nodeId: string): number;
+/** Get degree for all entity nodes (type === 'entity') in the graph. */
+export declare function getEntitiesWithDegrees(graph: DirectedGraph<GraphNodeAttrs, GraphEdgeAttrs>): Array<{
+    id: string;
+    degree: number;
+    label: string;
+}>;
+/** Compute adaptive degree range for filtering entity nodes.
+ *  - d_max = min(50, floor(graph.order / 5))
+ *  - d_min = 1 by default
+ *  Small graphs auto-shrink: 30 nodes → d_max=6, 100 nodes → d_max=20
+ */
+export declare function adaptiveDegreeRange(graph: DirectedGraph<GraphNodeAttrs, GraphEdgeAttrs>, opts?: {
+    minDegree?: number;
+    maxDegreeCap?: number;
+}): {
+    min: number;
+    max: number;
+};
+/** Filter entity nodes within the adaptive degree range. */
+export declare function filterEntitiesByDegree(graph: DirectedGraph<GraphNodeAttrs, GraphEdgeAttrs>, opts?: {
+    minDegree?: number;
+    maxDegreeCap?: number;
+}): Array<{
+    id: string;
+    degree: number;
+    label: string;
+}>;
+//# sourceMappingURL=degree-utils.d.ts.map

package/dist/deep/degree-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"degree-utils.d.ts","sourceRoot":"","sources":["../../src/deep/degree-utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5D,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,CAAC,cAAc,EAAE,cAAc,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE5G;AAED,wEAAwE;AACxE,wBAAgB,sBAAsB,CAClC,KAAK,EAAE,aAAa,CAAC,cAAc,EAAE,cAAc,CAAC,GACrD,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAYtD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAC/B,KAAK,EAAE,aAAa,CAAC,cAAc,EAAE,cAAc,CAAC,EACpD,IAAI,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAK9B;AAED,4DAA4D;AAC5D,wBAAgB,sBAAsB,CAClC,KAAK,EAAE,aAAa,CAAC,cAAc,EAAE,cAAc,CAAC,EACpD,IAAI,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,GACrD,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAGtD"}

package/dist/deep/degree-utils.js

@@ -0,0 +1,42 @@
+/**
+ * On-demand degree computation for entity nodes.
+ *
+ * Degree is NOT stored in node attributes — it's computed on-the-fly
+ * from the graph topology using graphology's O(1) inDegree/outDegree.
+ * This ensures degree is always consistent with the current graph state.
+ */
+/** Get the total degree (in + out) for a single node. O(1) via graphology. */
+export function getEntityDegree(graph, nodeId) {
+    return graph.inDegree(nodeId) + graph.outDegree(nodeId);
+}
+/** Get degree for all entity nodes (type === 'entity') in the graph. */
+export function getEntitiesWithDegrees(graph) {
+    const result = [];
+    graph.forEachNode((node, attrs) => {
+        if (attrs.type === 'entity') {
+            result.push({
+                id: node,
+                degree: getEntityDegree(graph, node),
+                label: attrs.label,
+            });
+        }
+    });
+    return result.sort((a, b) => b.degree - a.degree);
+}
+/** Compute adaptive degree range for filtering entity nodes.
+ *  - d_max = min(50, floor(graph.order / 5))
+ *  - d_min = 1 by default
+ *  Small graphs auto-shrink: 30 nodes → d_max=6, 100 nodes → d_max=20
+ */
+export function adaptiveDegreeRange(graph, opts) {
+    const dMin = opts?.minDegree ?? 1;
+    const cap = opts?.maxDegreeCap ?? 50;
+    const dMax = Math.min(cap, Math.floor(graph.order / 5));
+    return { min: dMin, max: Math.max(dMax, dMin) };
+}
+/** Filter entity nodes within the adaptive degree range. */
+export function filterEntitiesByDegree(graph, opts) {
+    const range = adaptiveDegreeRange(graph, opts);
+    return getEntitiesWithDegrees(graph).filter(e => e.degree >= range.min && e.degree <= range.max);
+}
+//# sourceMappingURL=degree-utils.js.map

package/dist/deep/degree-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"degree-utils.js","sourceRoot":"","sources":["../../src/deep/degree-utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,8EAA8E;AAC9E,MAAM,UAAU,eAAe,CAAC,KAAoD,EAAE,MAAc;IAChG,OAAO,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AAC5D,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,sBAAsB,CAClC,KAAoD;IAEpD,MAAM,MAAM,GAAyD,EAAE,CAAC;IACxE,KAAK,CAAC,WAAW,CAAC,CAAC,IAAY,EAAE,KAAqB,EAAE,EAAE;QACtD,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC1B,MAAM,CAAC,IAAI,CAAC;gBACR,EAAE,EAAE,IAAI;gBACR,MAAM,EAAE,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC;gBACpC,KAAK,EAAE,KAAK,CAAC,KAAK;aACrB,CAAC,CAAC;QACP,CAAC;IACL,CAAC,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;AACtD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAC/B,KAAoD,EACpD,IAAoD;IAEpD,MAAM,IAAI,GAAG,IAAI,EAAE,SAAS,IAAI,CAAC,CAAC;IAClC,MAAM,GAAG,GAAG,IAAI,EAAE,YAAY,IAAI,EAAE,CAAC;IACrC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;IACxD,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;AACpD,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,sBAAsB,CAClC,KAAoD,EACpD,IAAoD;IAEpD,MAAM,KAAK,GAAG,mBAAmB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC/C,OAAO,sBAAsB,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC;AACrG,CAAC"}

package/dist/deep/extractor.d.ts

@@ -1,10 +1,11 @@
 /**
- * Content extraction using linkedom + @mozilla/readability
+ * Content extraction: Defuddle (linkedom) → Playwright fallback
  */
 export interface ExtractorOptions {
     timeoutMs?: number;
     concurrency?: number;
     maxResponseBytes?: number;
+    playwright?: boolean;
 }
 export interface ExtractedContent {
     title: string;
@@ -16,14 +17,18 @@ export interface ExtractedContent {
     length: number;
     extractedAt: number;
     error?: string;
+    method?: 'defuddle' | 'playwright';
 }
 export declare class ContentExtractor {
     private timeoutMs;
     private concurrency;
     private maxResponseBytes;
+    private usePlaywright;
     constructor(options?: ExtractorOptions);
     extract(url: string): Promise<ExtractedContent>;
-    extractFromHtml(html: string, url: string): ExtractedContent;
+    private fetchHtml;
+    extractFromHtml(html: string, url: string): Promise<ExtractedContent>;
+    private playwrightExtract;
     extractBatch(urls: string[]): Promise<ExtractedContent[]>;
 }
 //# sourceMappingURL=extractor.d.ts.map

package/dist/deep/extractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extractor.d.ts","sourceRoot":"","sources":["../../src/deep/extractor.ts"],"names":[],"mappings":"AAAA;;GAEG;AASH,MAAM,WAAW,gBAAgB;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,gBAAgB;IACzB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,gBAAgB,CAAS;gBAErB,OAAO,CAAC,EAAE,gBAAgB;IAMhC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA8DrD,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,gBAAgB;IAyCtD,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;CASlE"}
+{"version":3,"file":"extractor.d.ts","sourceRoot":"","sources":["../../src/deep/extractor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAWH,MAAM,WAAW,gBAAgB;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,UAAU,GAAG,YAAY,CAAC;CACtC;AA8ED,qBAAa,gBAAgB;IACzB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,aAAa,CAAU;gBAEnB,OAAO,CAAC,EAAE,gBAAgB;IAOhC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;YA8BvC,SAAS;IA2BjB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;YAI7D,iBAAiB;IA2BzB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;CAUlE"}

package/dist/deep/extractor.js

@@ -1,65 +1,116 @@
 /**
- * Content extraction using linkedom + @mozilla/readability
+ * Content extraction: Defuddle (linkedom) → Playwright fallback
  */
 import { parseHTML } from 'linkedom';
-import { Readability } from '@mozilla/readability';
+import { Defuddle } from 'defuddle/node';
 const DEFAULT_TIMEOUT_MS = 10_000;
 const DEFAULT_CONCURRENCY = 3;
-const MAX_RESPONSE_BYTES = 5 * 1024 * 1024; // 5MB
+const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
+const MIN_CONTENT_LENGTH = 100;
+const PW_THRESHOLD = 50;
+let _browser = null;
+let _pwModule = null;
+async function loadPlaywright() {
+    if (_pwModule)
+        return _pwModule;
+    try {
+        // @ts-ignore — playwright is an optional peer dependency
+        _pwModule = await import('playwright');
+        return _pwModule;
+    }
+    catch {
+        return null;
+    }
+}
+async function getBrowser() {
+    if (_browser)
+        return _browser;
+    const pw = await loadPlaywright();
+    if (!pw)
+        return null;
+    _browser = await pw.chromium.launch({ headless: true });
+    return _browser;
+}
+async function closeBrowser() {
+    if (_browser) {
+        await _browser.close();
+        _browser = null;
+    }
+}
+async function defuddleExtract(html, url) {
+    try {
+        const { document } = parseHTML(html);
+        const result = await Defuddle(document, url, {
+            markdown: true,
+            useAsync: false,
+        });
+        const content = (result.content || '').trim();
+        if (!content) {
+            return {
+                title: result.title || '',
+                content: '',
+                excerpt: result.description || '',
+                url,
+                byline: result.author || undefined,
+                siteName: result.site || undefined,
+                length: 0,
+                extractedAt: Date.now(),
+                method: 'defuddle',
+                error: 'Defuddle could not extract content',
+            };
+        }
+        return {
+            title: result.title || '',
+            content,
+            excerpt: result.description || '',
+            url,
+            byline: result.author || undefined,
+            siteName: result.site || undefined,
+            length: result.wordCount || content.length,
+            extractedAt: Date.now(),
+            method: 'defuddle',
+        };
+    }
+    catch (error) {
+        return {
+            title: '',
+            content: '',
+            excerpt: '',
+            url,
+            length: 0,
+            extractedAt: Date.now(),
+            method: 'defuddle',
+            error: error instanceof Error ? error.message : 'Defuddle parsing failed',
+        };
+    }
+}
 export class ContentExtractor {
     timeoutMs;
     concurrency;
     maxResponseBytes;
+    usePlaywright;
     constructor(options) {
         this.timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
         this.concurrency = options?.concurrency ?? DEFAULT_CONCURRENCY;
         this.maxResponseBytes = options?.maxResponseBytes ?? MAX_RESPONSE_BYTES;
+        this.usePlaywright = options?.playwright ?? false;
     }
     async extract(url) {
         try {
-            const response = await fetch(url, {
-                headers: {
-                    'User-Agent': 'Mozilla/5.0 (compatible; SxngDeepSearch/1.0)',
-                    'Accept': 'text/html,application/xhtml+xml',
-                },
-                signal: AbortSignal.timeout(this.timeoutMs),
-            });
-            if (!response.ok) {
-                return {
-                    title: '',
-                    content: '',
-                    excerpt: '',
-                    url,
-                    length: 0,
-                    extractedAt: Date.now(),
-                    error: `HTTP ${response.status}: ${response.statusText}`,
-                };
+            const html = await this.fetchHtml(url);
+            const result = await defuddleExtract(html, url);
+            if (result.content.length >= MIN_CONTENT_LENGTH)
+                return result;
+            // Defuddle insufficient → Playwright fallback
+            if (this.usePlaywright && result.content.length < PW_THRESHOLD) {
+                const pwResult = await this.playwrightExtract(url);
+                if (pwResult && pwResult.content.length > result.content.length)
+                    return pwResult;
             }
-            const contentLength = response.headers.get('content-length');
-            if (contentLength && parseInt(contentLength, 10) > this.maxResponseBytes) {
-                return {
-                    title: '',
-                    content: '',
-                    excerpt: '',
-                    url,
-                    length: 0,
-                    extractedAt: Date.now(),
-                    error: `Response too large: ${contentLength} bytes (max ${this.maxResponseBytes})`,
-                };
+            if (result.content.length < MIN_CONTENT_LENGTH && !result.error) {
+                result.error = 'Extracted content too short';
             }
-            const html = await response.text();
-            if (html.length > this.maxResponseBytes) {
-                return {
-                    title: '',
-                    content: '',
-                    excerpt: '',
-                    url,
-                    length: 0,
-                    extractedAt: Date.now(),
-                    error: `Response too large: ${html.length} bytes (max ${this.maxResponseBytes})`,
-                };
-            }
-            return this.extractFromHtml(html, url);
+            return result;
         }
         catch (error) {
             return {
@@ -73,43 +124,56 @@ export class ContentExtractor {
             };
         }
     }
-    extractFromHtml(html, url) {
+    async fetchHtml(url) {
+        const response = await fetch(url, {
+            headers: {
+                'User-Agent': 'Mozilla/5.0 (compatible; SxngDeepSearch/1.0)',
+                'Accept': 'text/html,application/xhtml+xml',
+            },
+            signal: AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+        const contentLength = response.headers.get('content-length');
+        if (contentLength && parseInt(contentLength, 10) > this.maxResponseBytes) {
+            throw new Error(`Response too large: ${contentLength} bytes (max ${this.maxResponseBytes})`);
+        }
+        const html = await response.text();
+        if (html.length > this.maxResponseBytes) {
+            throw new Error(`Response too large: ${html.length} bytes (max ${this.maxResponseBytes})`);
+        }
+        return html;
+    }
+    // Sync wrapper for backward compat — uses Defuddle with useAsync:false
+    // Note: still async internally because defuddle/node export is async
+    async extractFromHtml(html, url) {
+        return defuddleExtract(html, url);
+    }
+    async playwrightExtract(url) {
+        const browser = await getBrowser();
+        if (!browser)
+            return null;
         try {
-            const { document } = parseHTML(html);
-            const reader = new Readability(document, { charThreshold: 100 });
-            const article = reader.parse();
-            if (!article || !article.textContent) {
-                return {
-                    title: '',
-                    content: '',
-                    excerpt: '',
-                    url,
-                    length: 0,
-                    extractedAt: Date.now(),
-                    error: 'Readability could not extract content',
-                };
+            const page = await browser.newPage();
+            await page.setExtraHTTPHeaders({ 'User-Agent': 'Mozilla/5.0 (compatible; SxngDeepSearch/1.0)' });
+            const response = await page.goto(url, {
+                waitUntil: 'networkidle',
+                timeout: this.timeoutMs,
+            });
+            if (!response || !response.ok()) {
+                await page.close();
+                return null;
             }
-            return {
-                title: article.title || '',
-                content: article.textContent.replace(/\n{3,}/g, '\n\n').trim(),
-                excerpt: article.excerpt || '',
-                url,
-                byline: article.byline || undefined,
-                siteName: article.siteName || undefined,
-                length: article.length || article.textContent.length,
-                extractedAt: Date.now(),
-            };
+            await page.waitForTimeout(1000);
+            const html = await page.content();
+            await page.close();
+            const result = await defuddleExtract(html, url);
+            result.method = 'playwright';
+            return result;
         }
-        catch (error) {
-            return {
-                title: '',
-                content: '',
-                excerpt: '',
-                url,
-                length: 0,
-                extractedAt: Date.now(),
-                error: error instanceof Error ? error.message : 'HTML parsing failed',
-            };
+        catch {
+            return null;
         }
     }
     async extractBatch(urls) {
@@ -119,6 +183,7 @@ export class ContentExtractor {
             const batchResults = await Promise.all(batch.map(u => this.extract(u)));
             results.push(...batchResults);
         }
+        await closeBrowser();
         return results;
     }
 }

package/dist/deep/extractor.js.map

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

package/dist/deep/graph-explore.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Agent-style knowledge graph exploration.
+ *
+ * Two-step interaction model:
+ *   graph-explore: inspect all relations around a seed entity (summary view)
+ *   graph-drill:   follow specific relations from an entity (targeted retrieval)
+ *
+ * Also includes dead-end detection and alternative path suggestion.
+ */
+import { DirectedGraph } from 'graphology';
+import { GraphNodeAttrs, GraphEdgeAttrs } from './graph.js';
+export interface RelationTarget {
+    nodeId: string;
+    label: string;
+    type: string;
+    weight: number;
+}
+export interface RelationGroup {
+    relation: string;
+    targets: RelationTarget[];
+}
+export interface ExploreResult {
+    entity: {
+        id: string;
+        label: string;
+        type: string;
+        score?: number;
+        degree: number;
+    };
+    outgoingRelations: RelationGroup[];
+    incomingRelations: RelationGroup[];
+    suggestedNextSteps: string[];
+}
+export interface DrillResult {
+    seed: string;
+    relations: string[];
+    triples: Array<{
+        source: string;
+        sourceLabel: string;
+        relation: string;
+        target: string;
+        targetLabel: string;
+        weight: number;
+    }>;
+    nextSteps: string[];
+}
+export interface DeadEndInfo {
+    entityId: string;
+    reason: 'low_degree' | 'only_mentioned_in' | 'already_visited';
+    alternativePaths: Array<{
+        fromEntity: string;
+        fromLabel: string;
+        relation: string;
+        toEntity: string;
+        toLabel: string;
+        score: number;
+    }>;
+}
+export interface EntitySuggestion {
+    id: string;
+    label: string;
+    distance: number;
+}
+/** Explore all relations around a seed entity. */
+export declare function exploreSeedEntity(graph: DirectedGraph<GraphNodeAttrs, GraphEdgeAttrs>, seedLabel: string): ExploreResult | {
+    error: string;
+    suggestions: EntitySuggestion[];
+};
+/** Follow specific relations from a seed entity. */
+export declare function drillByRelations(graph: DirectedGraph<GraphNodeAttrs, GraphEdgeAttrs>, seedLabel: string, relations: string[]): DrillResult | {
+    error: string;
+    suggestions: EntitySuggestion[];
+};
+/** Detect if an entity is a dead end and suggest alternatives. */
+export declare function detectDeadEnd(graph: DirectedGraph<GraphNodeAttrs, GraphEdgeAttrs>, entityId: string, visited?: Set<string>): DeadEndInfo | null;
+export interface TraverseResult {
+    pathId: string;
+    pathType: string;
+    label: string;
+    hops: Array<{
+        index: number;
+        entityId: string;
+        entityLabel: string;
+        entityType: string;
+        relation?: string;
+    }>;
+    sources: {
+        resultCount: number;
+        domains: string[];
+        rounds: number[];
+    };
+}
+/** Traverse a path: node and return the ordered reasoning chain. */
+export declare function traversePath(graph: DirectedGraph<GraphNodeAttrs, GraphEdgeAttrs>, pathId: string): TraverseResult | {
+    error: string;
+    availablePaths: string[];
+};
+export interface SearchResult {
+    id: string;
+    label: string;
+    score: number;
+}
+/** Keyword search across entity labels. Returns entity IDs ranked by score × degree. */
+export declare function searchEntities(graph: DirectedGraph<GraphNodeAttrs, GraphEdgeAttrs>, keyword: string, limit?: number): SearchResult[];
+/** Format explore result as Markdown. */
+export declare function formatExploreAsMarkdown(result: ExploreResult): string;
+/** Format drill result as Markdown. */
+export declare function formatDrillAsMarkdown(result: DrillResult): string;
+/** Format dead-end info as Markdown. */
+export declare function formatDeadEndAsMarkdown(info: DeadEndInfo): string;
+/** Format traverse result as Markdown. */
+export declare function formatTraverseAsMarkdown(result: TraverseResult): string;
+/** Format search results as Markdown. */
+export declare function formatSearchAsMarkdown(results: SearchResult[], keyword: string): string;
+//# sourceMappingURL=graph-explore.d.ts.map