pi-searxng-aggregator

A pi extension that queries a SearXNG search instance and aggregates results into per-topic JSON files. Results from repeated searches with the same query are appended to the same file, and can be read back using mode='list'.

Prerequisites

A SearXNG instance must be running and reachable. The extension uses the following priority chain to determine the base URL:

1. SEARXNG_BASE_URL environment variable (highest priority)
2. searxng.baseUrl in ~/.pi/agent/settings.json
3. http://localhost:8080 (default fallback)

Environment variable

export SEARXNG_BASE_URL=https://your-searxng.example.com

Settings file

Add the searxng.baseUrl key to your global settings file (~/.pi/agent/settings.json):

{
  "searxng": {
    "baseUrl": "https://your-searxng.example.com"
  }
}

Note: Non-local SearXNG instances (public instances, remote servers, etc.) are fully supported.

Local SearXNG Setup (Docker)

The simplest way to run SearXNG locally is with the official Docker image:

# Create data and config directories
mkdir -p ~/.config/searxng/{data,config}

# Run the container
docker run -d \
  --name searxng \
  -p 8080:8080 \
  -v ~/.config/searxng/data:/var/cache/searxng \
  -v ~/.config/searxng/config:/etc/searxng \
  searxng/searxng:latest

Verify it's running:

curl http://localhost:8080/search?q=test

The container persists data in ~/.config/searxng/, so your settings and cache survive restarts.

Quick Start

Install via npm (recommended)

pi install npm:pi-searxng-aggregator

Usage

Ask pi to search with SearXNG. Results are saved to a per-topic JSON file in the system temp directory.

Parameters

• query (required): The search query text
• engines (optional): Search engines, e.g. ["google", "duckduckgo"]
• categories (optional): Result categories, e.g. ["general", "images", "news"]
• language (optional): Language code, e.g. "en"
• filename (optional): Override the auto-generated filename slug for explicit grouping. Related searches share the same file.
• mode (optional): "search" (default) queries SearXNG; "list" reads a previously aggregated file without searching

Examples

• Search a query: "Search for latest AI news using searxng"
• Group related searches: "Search for Rust async and Tokio benchmarks, filename: 'async-rust'"
• Read previous results: "List aggregated results for async-rust"

Aggregated File Format

Results are saved as JSON in the system temp directory (e.g. /tmp/pi-searxng/). Each file has this structure:

{
  "filename": "async-rust",
  "queries": [
    {
      "id": "a3f1b2c4-...",
      "originalQuery": "Rust async benchmarks",
      "timestamp": 1715420000000,
      "params": { "engines": ["google"], "language": "en" },
      "results": [
        { "title": "...", "url": "...", "content": "...", "engine": "google", "category": "general", "score": 0.95 }
      ]
    }
  ],
  "totalQueries": 1,
  "totalResults": 1
}

• filename — slug for the file
• queries — array of all searches under this topic (appended on repeated searches)
• totalQueries / totalResults — summary counts
• Each result contains title, url, content, engine, category, score