perplexica-search

# Perplexica Search Skill

AI-powered search using your **local** Perplexica instance. This skill calls Perplexica's search API for deep research (quality mode), returns the answer and cited sources in OpenClaw, and leaves search/RAG state in Perplexica. **Local-only**: only `localhost`, `127.0.0.1`, `::1`, or `host.docker.internal` (Docker) are allowed; remote URLs are rejected. HTTP redirects are not followed, so the client cannot be sent to a non-local host.

## When to Use

Use this skill when the user wants to:

- Search the web with AI-powered reasoning
- Get answers with cited sources
- Perform deep research on a topic (use `--mode quality`)
- Search academic papers or discussions
- Use a local, privacy-focused search engine
- Get structured search results with metadata

## Prerequisites

- **python3** (required to run the script)
- Perplexica running locally (default: `http://localhost:3000`)
- At least one chat model provider configured in Perplexica
- At least one embedding model configured

## Usage

Run the script by **path**; do not rely on `cd` to the skill directory. The script finds its config from its own location. Use the skill directory your environment provides (e.g. `{baseDir}` or the path where this skill is installed).

```bash
# Basic search (replace <SKILL_DIR> with the actual skill path, e.g. ~/.openclaw/skills/perplexica-search or {baseDir})
python3 <SKILL_DIR>/scripts/perplexica_search.py "What is quantum computing?"

# Specify optimization mode
python3 <SKILL_DIR>/scripts/perplexica_search.py "Latest AI developments" --mode quality

# Search specific sources
python3 <SKILL_DIR>/scripts/perplexica_search.py "Machine learning papers" --sources academic

# Different local port or Docker host (allowed: localhost, 127.0.0.1, ::1, host.docker.internal)
python3 <SKILL_DIR>/scripts/perplexica_search.py "Climate change research" --url http://127.0.0.1:3000
python3 <SKILL_DIR>/scripts/perplexica_search.py "Query" --url http://host.docker.internal:...

# Perplexica Search Skill 🔍

An [OpenClaw](https://open-claw.bot) skill that runs AI-powered search against your **local** [Perplexica](https://github.com/ItzCrazyKns/Perplexica) instance. Uses deep research (quality mode), web search, and LLM reasoning to return answers with cited sources in OpenClaw while keeping search/RAG state in Perplexica.

**Local-only:** only `localhost`, `127.0.0.1`, `::1`, or `host.docker.internal` (Docker) are allowed; remote URLs are rejected. HTTP redirects are not followed.

## Installation

```bash
# From ClawHub (when published)
clawhub install perplexica-search

# From GitHub
git clone https://github.com/eplt/perplexica-search.git ~/.openclaw/skills/perplexica-search
```

## Prerequisites

- **python3** (required)
- Perplexica running locally (default: `http://localhost:3000`)
- At least one chat model provider configured in Perplexica
- Python 3.8+

## Quick Start

```bash
# Basic search
python3 scripts/perplexica_search.py "What is quantum computing?"

# Quality mode with academic sources
python3 scripts/perplexica_search.py "Transformer architecture 2024" --mode quality --sources academic

# JSON output for programmatic use
python3 scripts/perplexica_search.py "Python async best practices" --json
```

## Usage

```
usage: perplexica_search.py [-h] [-u URL] [-m {speed,balanced,quality}]
                            [-s SOURCES] [--chat-model CHAT_MODEL]
                            [--embedding-model EMBEDDING_MODEL]
                            [-i INSTRUCTIONS] [--history HISTORY] [-j]
                            [--stream]
                            query

AI-powered search using local Perplexica instance

positional arguments:
  query                 Search query

options:
  -h, --help            show this help message and exit
  -u URL, --url URL     Local Perplexica base URL only (default: http://localhost:3000). Allowed: localhost, 127.0.0.1, ::1, host.docker.internal.
  -m {speed,balanced,quality}, --mode {speed,balanced,q...