sxng-cli 1.0.5 → 1.0.7

package/README.md

@@ -1,6 +1,6 @@
 # SearXNG CLI
 
-A command-line interface for searching with SearXNG, a privacy-respecting meta search engine.
+A command-line interface for searching with SearXNG, a privacy-respecting meta search engine. Supports deep multi-round search with knowledge graph, session accumulation, and content extraction.
 
 ## Installation
 
@@ -34,13 +34,15 @@ sxng "your search query"
 
 Configuration can be provided via:
 1. Environment variables (highest priority)
-2. Config file: `./searxng.config.json`
+2. Config file: `./searxng.config.json` or `~/.sxng/config.json`
 3. Default values (lowest priority)
 
 See `searxng.config.example.json` for an example configuration.
 
 ## Usage
 
+### Basic Search
+
 ```bash
 # Simple search
 sxng "TypeScript tutorial"
@@ -57,8 +59,8 @@ sxng --categories it,science "machine learning"
 # Recent results only
 sxng --time week "latest news"
 
-# Output as CSV
-sxng "docker tutorial" --format csv > results.csv
+# Output as JSON
+sxng -f json "docker tutorial"
 
 # Check server health
 sxng --health
@@ -70,6 +72,120 @@ sxng --engines-list
 sxng --categories-list
 ```
 
+### Multi-Query Search
+
+Run multiple queries with RRF (Reciprocal Rank Fusion) result fusion and deduplication:
+
+```bash
+sxng --queries "tokio tutorial,rust async basics,tokio vs async-std"
+```
+
+### Content Extraction
+
+Extract full article content from web pages:
+
+```bash
+# Extract from specific URLs
+sxng extract --urls "https://example.com/article1,https://example.com/article2"
+
+# Extract from search results JSON file
+sxng extract --from-json search-results.json
+```
+
+## Deep Search
+
+Deep search enables multi-round iterative research with session accumulation and knowledge graph building.
+
+### Session Management
+
+```bash
+# Create a new session with auto-generated name
+sxng --session new --owner "research-agent" --desc "Rust async research" "rust async ecosystem"
+
+# List all sessions
+sxng session-list
+
+# Delete a specific session
+sxng session-delete <session-name>
+
+# Delete sessions older than N hours
+sxng session-delete --older 24
+```
+
+### Deep Search Workflow
+
+The deep search flow follows an iterative loop: search → extract → analyze → build graph → decide.
+
+```bash
+# Round 1: Create session and search
+sxng --session new --owner "agent-1" --desc "async ecosystem research" "rust async ecosystem"
+# Note the returned session path, e.g., ~/.sxng/sessions/<session-name>
+
+# Extract content from results
+sxng extract --session ~/.sxng/sessions/<session-name>
+
+# Add entities and relationships to knowledge graph
+sxng graph-add ~/.sxng/sessions/<session-name> --data '{
+  "entities": [
+    {"label": "tokio", "entityType": "runtime", "score": 0.95},
+    {"label": "async-std", "entityType": "runtime", "score": 0.85}
+  ],
+  "edges": [
+    {"source": "e:tokio", "target": "e:async_std", "relation": "alternative_to", "weight": 0.9}
+  ]
+}'
+
+# Query the knowledge graph
+sxng query-graph ~/.sxng/sessions/<session-name> --seeds "tokio" --depth 2
+
+# Round 2: Search with multiple queries (results accumulate in session)
+sxng --session ~/.sxng/sessions/<session-name> --queries "tokio vs async-std comparison,rust async benchmark 2024"
+
+# Extract again and continue the loop...
+```
+
+### Session Data Structure
+
+Each session stores three files in `~/.sxng/sessions/<session-name>/`:
+
+- **`results.json`** — Accumulated search result pool (URL dedup, multi-round accumulation)
+- **`graph.json`** — Knowledge graph (structural + semantic layers)
+- **`meta.json`** — Session metadata (owner, description, timestamps)
+
+### Knowledge Graph
+
+The graph has two layers:
+
+**Structural Layer** (auto-built by CLI every search):
+
+| Node type | Prefix | Attributes |
+|-----------|--------|------------|
+| query | `q:` | label, query, round |
+| result | `r:` | label, url, title, rank |
+| domain | `d:` | label, domain |
+
+**Semantic Layer** (added via `graph-add`):
+
+| Node type | Prefix | Attributes |
+|-----------|--------|------------|
+| entity | `e:` | label, entityType, score |
+
+## Options Reference
+
+| Option | Short | Description | Example |
+|--------|-------|-------------|---------|
+| `--limit` | `-l` | Max results | `-l 20` |
+| `--engines` | `-e` | Specific search engines | `-e google,github` |
+| `--categories` | `-c` | Filter by category | `-c it,science` |
+| `--page` | `-p` | Pagination | `-p 2` |
+| `--lang` | | Result language | `--lang zh` |
+| `--time` | | Time filter | `--time week` |
+| `--format` | `-f` | Output format | `-f json` |
+| `--queries` | | Multi-query with RRF fusion | `--queries "q1,q2,q3"` |
+| `--session` | | Session directory or "new" | `--session new` |
+| `--owner` | | Session owner identifier | `--owner "agent-1"` |
+| `--desc` | | Session description | `--desc "research topic"` |
+
 ## Environment Variables
 
 | Variable | Description | Default |

package/dist/commands/build-graph.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Build-graph subcommand - construct knowledge graph from search results
+ */
+export interface BuildGraphOptions {
+    inputs: string[];
+}
+export declare function runBuildGraph(options: BuildGraphOptions): Promise<number>;
+//# sourceMappingURL=build-graph.d.ts.map

package/dist/commands/build-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-graph.d.ts","sourceRoot":"","sources":["../../src/commands/build-graph.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,MAAM,WAAW,iBAAiB;IAC9B,MAAM,EAAE,MAAM,EAAE,CAAC;CACpB;AA0BD,wBAAsB,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsD/E"}

package/dist/commands/build-graph.js

@@ -0,0 +1,70 @@
+/**
+ * Build-graph subcommand - construct knowledge graph from search results
+ */
+import { readFileSync } from 'fs';
+import { buildGraphFromResults, serializeGraph, graphStats } from '../deep/graph.js';
+import { createSuccessEnvelope, createErrorEnvelope } from '../protocol.js';
+function loadResultsFromFiles(files) {
+    const allResults = [];
+    for (const file of files) {
+        try {
+            const raw = readFileSync(file, 'utf-8');
+            const parsed = JSON.parse(raw);
+            // Handle envelope format
+            let data = parsed;
+            if (parsed.status === 'ok' && parsed.data) {
+                data = parsed.data;
+            }
+            const results = data.results || [];
+            allResults.push(...results);
+        }
+        catch {
+            // Skip invalid files silently
+        }
+    }
+    return allResults;
+}
+export async function runBuildGraph(options) {
+    if (options.inputs.length === 0) {
+        const envelope = createErrorEnvelope('MISSING_INPUT', 'No input files provided for graph building', { hint: 'Use: sxng build-graph --inputs file1.json,file2.json' });
+        console.log(JSON.stringify(envelope, null, 2));
+        return 1;
+    }
+    const allResults = loadResultsFromFiles(options.inputs);
+    if (allResults.length === 0) {
+        const envelope = createErrorEnvelope('NO_RESULTS', 'No search results found in input files', { hint: 'Ensure input files contain valid search results with a results array' });
+        console.log(JSON.stringify(envelope, null, 2));
+        return 1;
+    }
+    // Collect all queries from input files
+    const allQueries = [];
+    for (const file of options.inputs) {
+        try {
+            const raw = readFileSync(file, 'utf-8');
+            const parsed = JSON.parse(raw);
+            let data = parsed;
+            if (parsed.status === 'ok' && parsed.data) {
+                data = parsed.data;
+            }
+            if (data.queries) {
+                allQueries.push(...data.queries);
+            }
+            else if (data.query) {
+                allQueries.push(data.query);
+            }
+        }
+        catch {
+            // Skip
+        }
+    }
+    const graph = buildGraphFromResults(allResults, allQueries);
+    const serialized = serializeGraph(graph);
+    const stats = graphStats(graph);
+    const envelope = createSuccessEnvelope({
+        stats,
+        graph: serialized,
+    });
+    console.log(JSON.stringify(envelope, null, 2));
+    return 0;
+}
+//# sourceMappingURL=build-graph.js.map

package/dist/commands/build-graph.js.map

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

package/dist/commands/extract.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Extract subcommand - content extraction from URLs or search results
+ */
+import { ContentExtractor } from '../deep/extractor.js';
+export interface ExtractOptions {
+    urls?: string[];
+    fromJson?: string;
+    session?: string;
+}
+export declare function runExtract(extractor: ContentExtractor, options: ExtractOptions): Promise<number>;
+//# sourceMappingURL=extract.d.ts.map

package/dist/commands/extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../src/commands/extract.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAoB,MAAM,sBAAsB,CAAC;AAK1E,MAAM,WAAW,cAAc;IAC3B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAYD,wBAAsB,UAAU,CAC5B,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE,cAAc,GACxB,OAAO,CAAC,MAAM,CAAC,CAyGjB"}

package/dist/commands/extract.js

@@ -0,0 +1,88 @@
+/**
+ * Extract subcommand - content extraction from URLs or search results
+ */
+import { createSuccessEnvelope, createErrorEnvelope } from '../protocol.js';
+import { readFileSync } from 'fs';
+import { loadSessionResults, mergeExtractedContent, resolveSessionPath } from '../deep/session.js';
+export async function runExtract(extractor, options) {
+    let urls = [];
+    // Resolve session path if provided
+    if (options.session) {
+        options.session = resolveSessionPath(options.session);
+    }
+    if (options.urls && options.urls.length > 0) {
+        urls = options.urls;
+    }
+    else if (options.session) {
+        // Read URLs from session results
+        const results = loadSessionResults(options.session);
+        if (results.length === 0) {
+            const envelope = createErrorEnvelope('SESSION_EMPTY', `Session has no results: ${options.session}`, { hint: 'Run a search with --session first to accumulate results' });
+            console.log(JSON.stringify(envelope, null, 2));
+            return 1;
+        }
+        urls = results.map(r => r.url).filter(u => typeof u === 'string' && u.length > 0);
+    }
+    else if (options.fromJson) {
+        try {
+            const raw = readFileSync(options.fromJson, 'utf-8');
+            const parsed = JSON.parse(raw);
+            // Handle envelope format
+            let data = parsed;
+            if (parsed.status === 'ok' && parsed.data) {
+                data = parsed.data;
+            }
+            // Extract URLs from results array
+            const results = data.results || [];
+            urls = results
+                .map((r) => r.url)
+                .filter((u) => typeof u === 'string' && u.length > 0);
+        }
+        catch (error) {
+            const envelope = createErrorEnvelope('FILE_READ_FAILED', `Failed to read or parse file: ${options.fromJson}`, { hint: 'Ensure the file exists and contains valid JSON with a results array' });
+            console.log(JSON.stringify(envelope, null, 2));
+            return 1;
+        }
+    }
+    else {
+        const envelope = createErrorEnvelope('MISSING_INPUT', 'No URLs or input file provided for extraction', { hint: 'Use: sxng extract --urls "url1,url2" or sxng extract --from-json results.json or sxng extract --session /tmp/s' });
+        console.log(JSON.stringify(envelope, null, 2));
+        return 1;
+    }
+    if (urls.length === 0) {
+        const envelope = createErrorEnvelope('NO_URLS', 'No URLs found to extract', { hint: 'Provide URLs directly or ensure the JSON/session contains results with URLs' });
+        console.log(JSON.stringify(envelope, null, 2));
+        return 1;
+    }
+    try {
+        const contents = await extractor.extractBatch(urls);
+        const extracted = contents.filter(c => !c.error && c.content.length > 100);
+        const failed = contents.filter(c => c.error || c.content.length <= 100).map(c => c.url);
+        // Merge extracted content into session if --session provided
+        let sessionMerge = null;
+        if (options.session) {
+            sessionMerge = mergeExtractedContent(options.session, contents);
+        }
+        const output = {
+            extracted,
+            failed,
+            stats: {
+                total: urls.length,
+                success: extracted.length,
+                failed: failed.length,
+            },
+        };
+        const envelope = createSuccessEnvelope({
+            ...output,
+            ...(sessionMerge ? { session: sessionMerge } : {}),
+        });
+        console.log(JSON.stringify(envelope, null, 2));
+        return 0;
+    }
+    catch (error) {
+        const envelope = createErrorEnvelope('EXTRACT_FAILED', error instanceof Error ? error.message : 'Content extraction failed', { retryable: true });
+        console.log(JSON.stringify(envelope, null, 2));
+        return 1;
+    }
+}
+//# sourceMappingURL=extract.js.map

package/dist/commands/extract.js.map

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

package/dist/commands/graph-add.d.ts

@@ -0,0 +1,13 @@
+/**
+ * graph-add subcommand - Add entities and edges to an entity-centric knowledge graph
+ *
+ * Agent (LLM) extracts entities from search results and sends them here.
+ * Each entity is connected to its source result via "mentions" edges.
+ * Result nodes store lightweight metadata (title, url, rank).
+ */
+export interface GraphAddOptions {
+    graphFile: string;
+    data: string;
+}
+export declare function runGraphAdd(options: GraphAddOptions): Promise<number>;
+//# sourceMappingURL=graph-add.d.ts.map

package/dist/commands/graph-add.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-add.d.ts","sourceRoot":"","sources":["../../src/commands/graph-add.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA2BH,MAAM,WAAW,eAAe;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CAChB;AAsBD,wBAAsB,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAoJ3E"}

package/dist/commands/graph-add.js

@@ -0,0 +1,155 @@
+/**
+ * graph-add subcommand - Add entities and edges to an entity-centric knowledge graph
+ *
+ * Agent (LLM) extracts entities from search results and sends them here.
+ * Each entity is connected to its source result via "mentions" edges.
+ * Result nodes store lightweight metadata (title, url, rank).
+ */
+import { readFileSync, writeFileSync, existsSync, statSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { deserializeGraph, serializeGraph, graphStats, entityId, resultId } from '../deep/graph.js';
+import { DirectedGraph } from 'graphology';
+import { createSuccessEnvelope, createErrorEnvelope } from '../protocol.js';
+/** Resolve graph file path — if directory (session), use graph.json inside it.
+ *  Pure name (no separators) is resolved to ~/.sxng/sessions/<name>
+ */
+function resolveGraphFile(path) {
+    // Pure name without path separators: resolve to default sessions dir
+    if (!path.includes('/') && !path.includes('\\')) {
+        path = join(homedir(), '.sxng', 'sessions', path);
+    }
+    try {
+        if (statSync(path).isDirectory()) {
+            return join(path, 'graph.json');
+        }
+    }
+    catch {
+        // Not a file/dir, return as-is
+    }
+    return path;
+}
+export async function runGraphAdd(options) {
+    const graphFile = resolveGraphFile(options.graphFile);
+    if (!graphFile) {
+        const envelope = createErrorEnvelope('MISSING_GRAPH_FILE', 'No graph file specified', { hint: 'Use: sxng graph-add graph.json --data \'...\'' });
+        console.log(JSON.stringify(envelope, null, 2));
+        return 1;
+    }
+    // Parse input data
+    let parsed;
+    try {
+        parsed = JSON.parse(options.data);
+    }
+    catch {
+        const envelope = createErrorEnvelope('INVALID_JSON', 'Failed to parse --data JSON', { hint: 'Ensure --data contains valid JSON with "entities", "results", and/or "edges" arrays' });
+        console.log(JSON.stringify(envelope, null, 2));
+        return 1;
+    }
+    // Load or create graph
+    let graph;
+    if (existsSync(graphFile)) {
+        try {
+            const raw = readFileSync(graphFile, 'utf-8');
+            const fileParsed = JSON.parse(raw);
+            const graphData = fileParsed.status === 'ok' && fileParsed.data?.graph
+                ? fileParsed.data.graph
+                : (fileParsed.nodes && fileParsed.edges ? fileParsed : null);
+            graph = graphData
+                ? deserializeGraph(graphData)
+                : new DirectedGraph();
+        }
+        catch {
+            const envelope = createErrorEnvelope('GRAPH_LOAD_FAILED', `Failed to load graph from: ${graphFile}`, { hint: 'Ensure the file contains a valid graphology graph' });
+            console.log(JSON.stringify(envelope, null, 2));
+            return 1;
+        }
+    }
+    else {
+        graph = new DirectedGraph();
+    }
+    let entitiesAdded = 0;
+    let resultsAdded = 0;
+    let edgesAdded = 0;
+    // Add entity nodes
+    for (const entity of parsed.entities || []) {
+        const id = entity.id || entityId(entity.label);
+        if (!graph.hasNode(id)) {
+            graph.mergeNode(id, {
+                type: 'entity',
+                label: entity.label,
+                entityType: entity.entityType,
+                score: entity.score,
+            });
+            entitiesAdded++;
+        }
+        else {
+            // Update existing entity
+            const existing = graph.getNodeAttributes(id);
+            graph.mergeNode(id, {
+                ...existing,
+                label: entity.label,
+                entityType: entity.entityType ?? existing.entityType,
+                score: entity.score ?? existing.score,
+            });
+        }
+    }
+    // Add result metadata nodes
+    for (const result of parsed.results || []) {
+        const id = resultId(result.url);
+        if (!graph.hasNode(id)) {
+            graph.mergeNode(id, {
+                type: 'result',
+                label: result.title,
+                url: result.url,
+                title: result.title,
+                rank: result.rank,
+            });
+            resultsAdded++;
+        }
+        else {
+            // Update rank if better
+            const existing = graph.getNodeAttributes(id);
+            if (result.rank !== undefined) {
+                graph.mergeNode(id, {
+                    ...existing,
+                    rank: result.rank < (existing.rank ?? Infinity) ? result.rank : existing.rank,
+                });
+            }
+        }
+    }
+    // Add edges (entity-entity and entity-result relationships)
+    const skippedEdges = [];
+    for (const edge of parsed.edges || []) {
+        if (!graph.hasNode(edge.source) || !graph.hasNode(edge.target)) {
+            skippedEdges.push({ source: edge.source, target: edge.target, relation: edge.relation });
+            continue;
+        }
+        graph.mergeEdge(edge.source, edge.target, {
+            relation: edge.relation,
+            weight: edge.weight ?? 1,
+        });
+        edgesAdded++;
+    }
+    // Save graph
+    const serialized = serializeGraph(graph);
+    const stats = graphStats(graph);
+    try {
+        writeFileSync(graphFile, JSON.stringify({ status: 'ok', data: { graph: serialized, stats } }, null, 2), 'utf-8');
+    }
+    catch (e) {
+        const envelope = createErrorEnvelope('GRAPH_WRITE_FAILED', `Failed to write graph to: ${graphFile}`, { hint: 'Check directory permissions and disk space', details: { error: e instanceof Error ? e.message : String(e) } });
+        console.log(JSON.stringify(envelope, null, 2));
+        return 1;
+    }
+    const envelope = createSuccessEnvelope({
+        entitiesAdded,
+        resultsAdded,
+        edgesAdded,
+        skippedEdges,
+        stats,
+    });
+    console.log(JSON.stringify(envelope, null, 2));
+    return 0;
+}
+//# sourceMappingURL=graph-add.js.map

package/dist/commands/graph-add.js.map

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

package/dist/commands/query-graph.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Query-graph subcommand - BFS subgraph extraction from knowledge graph
+ */
+export interface QueryGraphOptions {
+    graphFile: string;
+    seeds: string[];
+    depth: number;
+    format?: 'json' | 'md';
+}
+export declare function runQueryGraph(options: QueryGraphOptions): Promise<number>;
+//# sourceMappingURL=query-graph.d.ts.map

package/dist/commands/query-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-graph.d.ts","sourceRoot":"","sources":["../../src/commands/query-graph.ts"],"names":[],"mappings":"AAAA;;GAEG;AA2CH,MAAM,WAAW,iBAAiB;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsI/E"}