Merge pull request #1 from justyns/init-cookiecutter

Initial plugin

Author: justyns

.github/workflows/publish.yml

@@ -0,0 +1,46 @@
+name: Publish Python Package
+
+on:
+  release:
+    types: [created]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up uv
+      uses: astral-sh/setup-uv@v6
+      with:
+        enable-cache: true
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        uv sync --group test
+    - name: Run tests
+      run: |
+        uv run python -m pytest
+  deploy:
+    runs-on: ubuntu-latest
+    needs: [test]
+    environment: release
+    permissions:
+      id-token: write
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up uv
+      uses: astral-sh/setup-uv@v6
+      with:
+        enable-cache: true
+        python-version: "3.13"
+    - name: Build package
+      run: |
+        uv build
+    - name: Publish
+      uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/test.yml

@@ -0,0 +1,46 @@
+name: Test
+
+on: [push, pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up uv
+      uses: astral-sh/setup-uv@v6
+      with:
+        enable-cache: true
+        python-version: "3.12"
+    - name: Install dependencies
+      run: |
+        uv sync --group dev
+    - name: Run ruff linter
+      run: |
+        uv run ruff check .
+    - name: Run ruff formatter
+      run: |
+        uv run ruff format --check .
+
+  test:
+    runs-on: ubuntu-latest
+    needs: lint
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up uv
+      uses: astral-sh/setup-uv@v6
+      with:
+        enable-cache: true
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        uv sync --group test
+    - name: Run tests
+      run: |
+        uv run python -m pytest

.gitignore

@@ -0,0 +1,12 @@
+.venv
+__pycache__/
+*.py[cod]
+*$py.class
+venv
+.eggs
+.pytest_cache
+*.egg-info
+.DS_Store
+.vscode
+dist
+build

README.md

@@ -0,0 +1,79 @@
+# llm-tools-searxng
+
+[PyPI](https://img.shields.io/pypi/v/llm-tools-searxng.svg)](https://pypi.org/project/llm-tools-searxng/)
+[![Changelog](https://img.shields.io/github/v/release/justyns/llm-tools-searxng?include_prereleases&label=changelog)](https://github.com/justyns/llm-tools-searxng/releases)
+[![Tests](https://github.com/justyns/llm-tools-searxng/actions/workflows/test.yml/badge.svg)](https://github.com/justyns/llm-tools-searxng/actions/workflows/test.yml)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/justyns/llm-tools-searxng/blob/main/LICENSE)
+
+A tool to search the web using SearXNG search engines.
+
+## Installation
+
+Install this plugin in the same environment as [LLM](https://llm.datasette.io/).
+```bash
+llm install llm-tools-searxng
+```
+
+## Configuration
+
+By default, the tool does not have a default SEARXNG_URL set, you must set this environment variable to a searxng instance you have access to:
+
+```bash
+export SEARXNG_URL=https://your-searxng-instance.com
+export SEARXNG_METHOD=GET  # or POST (default)
+```
+
+**Note:** Public SearXNG instances typically don't allow API access or JSON output.
+
+## Usage
+
+### Simple search function
+
+Use the `searxng_search` function for basic web searches:
+
+```bash
+llm --tool searxng_search "latest developments in AI" --tools-debug
+```
+
+### With LLM chat
+
+This plugin works well with `llm chat`:
+
+```bash
+llm chat --tool searxng_search --tools-debug
+```
+
+### Python API usage
+
+```python
+import llm
+from llm_tools_searxng import SearXNG, searxng_search
+
+# Using the simple function
+model = llm.get_model("gpt-4.1-mini")
+result = model.chain(
+    "What are the latest developments in renewable energy?",
+    tools=[searxng_search]
+).text()
+```
+
+## Development
+
+To set up this plugin locally, first checkout the code. Then create a new virtual environment:
+
+```bash
+cd llm-tools-searxng
+uv sync --all-extras
+```
+
+Now install the dependencies and test dependencies:
+
+```bash
+llm install -e '.[test]'
+```
+
+To run the tests:
+
+```bash
+uv run python -m pytest
+```

llm_tools_searxng.py

@@ -0,0 +1,117 @@
+import json
+import os
+
+import httpx
+import llm
+
+
+class SearXNG:
+    """A tool for searching the web using SearXNG search engine"""
+
+    def __init__(self, base_url: str = None):
+        self.base_url = base_url or os.getenv("SEARXNG_URL")
+        if not self.base_url:
+            raise ValueError("SEARXNG_URL environment variable is required")
+        self.method = os.getenv("SEARXNG_METHOD", "POST").upper()
+
+    def search(
+        self,
+        query: str,
+        format: str = "json",
+        categories: str = None,
+        engines: str = None,
+        language: str = "en",
+        pageno: int = 1,
+        time_range: str = None,
+        safesearch: int = 1,
+    ) -> str:
+        """
+        Search the web using SearXNG.
+
+        Args:
+            query: The search query (required)
+            format: Output format (json, csv, rss) - default: json
+            categories: Comma separated list of search categories (optional)
+            engines: Comma separated list of search engines (optional)
+            language: Language code - default: en
+            pageno: Search page number - default: 1
+            time_range: Time range (day, month, year) - optional
+            safesearch: Safe search level (0, 1, 2) - default: 1
+        """
+        search_url = f"{self.base_url.rstrip('/')}/search"
+
+        params = {
+            "q": query,
+            "format": format,
+            "language": language,
+            "pageno": pageno,
+            "safesearch": safesearch,
+        }
+
+        if categories:
+            params["categories"] = categories
+        if engines:
+            params["engines"] = engines
+        if time_range:
+            params["time_range"] = time_range
+
+        try:
+            # TODO: Set user agent?
+            headers = None
+
+            with httpx.Client(follow_redirects=True, timeout=30.0, headers=headers) as client:
+                if self.method == "POST":
+                    response = client.post(search_url, data=params)
+                else:
+                    response = client.get(search_url, params=params)
+                response.raise_for_status()
+
+                if format == "json":
+                    result = response.json()
+                    if "results" in result:
+                        formatted_results = []
+                        for item in result["results"][:10]:
+                            formatted_result = {
+                                "title": item.get("title", ""),
+                                "url": item.get("url", ""),
+                                "snippet": item.get("content", ""),
+                                "engine": item.get("engine", ""),
+                            }
+                            formatted_results.append(formatted_result)
+
+                        summary = {
+                            "query": query,
+                            "number_of_results": len(result.get("results", [])),
+                            "results": formatted_results,
+                        }
+                        return json.dumps(summary, indent=2)
+                    else:
+                        return json.dumps(result, indent=2)
+                else:
+                    return response.text
+
+        except httpx.HTTPError as e:
+            raise Exception(f"HTTP error occurred: {e}")
+        except json.JSONDecodeError as e:
+            raise Exception(f"Error parsing JSON response: {e}")
+        except Exception as e:
+            raise Exception(f"Error performing search: {e}")
+
+
+def searxng_search(query: str) -> str:
+    """
+    Search the web using SearXNG. Returns a JSON string with results including
+    title, URL, snippet, and search engine used.
+
+    Args:
+        query: Search query to search for. SearxNG search syntax (https://docs.searxng.org/user/search-syntax.html) is supported.
+    """
+    searxng = SearXNG()
+    return searxng.search(query)
+
+
+@llm.hookimpl
+def register_tools(register):
+    if not os.environ.get("SEARXNG_URL"):
+        raise RuntimeError("SEARXNG_URL environment variable is not set.")
+    register(searxng_search)

pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "llm-tools-searxng"
+version = "0.1"
+description = "A tool to search the web using SearXNG."
+readme = "README.md"
+authors = [{name = "Justyn Shull"}]
+license = "Apache-2.0"
+classifiers = []
+requires-python = ">=3.9"
+dependencies = [
+    "httpx>=0.28.1",
+    "llm>=0.26",
+]
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.11.12",
+]
+
+[project.urls]
+Homepage = "https://github.com/justyns/llm-tools-searxng"
+Changelog = "https://github.com/justyns/llm-tools-searxng/releases"
+Issues = "https://github.com/justyns/llm-tools-searxng/issues"
+CI = "https://github.com/justyns/llm-tools-searxng/actions"
+
+[project.entry-points.llm]
+llm_tools_searxng = "llm_tools_searxng"
+
+[project.optional-dependencies]
+test = ["pytest", "llm-echo>=0.3a1", "pytest-httpx"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py39"
+
+[tool.ruff.lint]
+ignore = []
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"