how to contribute tooling

Tooling

Active contributors: Magnus Hedemark

Purpose

Build system, linters, CI workflows, and the SSX CLI that support development and deployment of SlopSearX.

SSX CLI

The ssx CLI at the repository root provides an agent-friendly wrapper around the SlopSearX API:

python ssx search "quantum computing" --categories science
python ssx engines
python ssx health
python ssx config

All commands support --json for programmatic output. The default output format is YAML+Markdown, optimized for AI agent consumption. The CLI discovers the server URL from the SSX_URL env var (default: http://localhost:8080).

Commands:

• ssx search <query> — Execute a search with optional category, engine, language, time-range, and page filters
• ssx engines — List all engines with their health status and categories
• ssx health — Check server and per-engine health
• ssx config — Show engine-to-categories mapping for runtime discovery

Linting

The project uses ruff for both linting and formatting:

ruff check .        # Lint all files
ruff format .       # Format all files

There is no separate formatter (no Black, isort, or flake8 config). Ruff handles everything. Configuration is in pyproject.toml under [tool.ruff].

CI/CD

The project has four GitHub Actions workflows in .github/workflows/:

ci.yml — Main CI

Runs on every push and PR. Two jobs:

1. Lint: ruff check .
2. Test: pytest -v on Python 3.12 and 3.13

docker.yml — Docker build and push

Builds the Docker image and pushes to GitHub Container Registry (ghcr.io). Triggered on pushes to main and on version tags (v*).

droid.yml — Factory Droid tagging

Marks commits with a Factory Droid tag for session tracking. Runs on push to main.

droid-review.yml — Factory Droid code review

Auto-reviews PRs using Factory Droid. Triggered on PR open and synchronize events.

Build and packaging

The project uses pyproject.toml with setuptools. Key scripts:

pip install -e ".[dev]"   # Development install with all extras
pytest -v                 # Run tests
ruff check .              # Lint

Dependencies are managed via pyproject.toml with a uv.lock file for reproducible installs.

Docker

Two Docker configurations exist:

• Dockerfile — Multi-stage build. Copies the project, installs dependencies, and runs uvicorn on port 8080.
• docker-compose.yml — Orchestrates SlopSearX + Valkey. Builds from the Dockerfile and connects to a Valkey 8 Alpine container.

The .dockerignore excludes .venv, .git, __pycache__, and test artifacts.

Kubernetes

The k8s/ directory contains Kustomize manifests for production deployment:

• Deployment with 3 replicas, resource requests/limits, and Valkey env vars
• ClusterIP service on port 8080
• HPA scaling from 3 to 100 replicas at 70% CPU utilization

Apply with: kubectl apply -k k8s/

Key source files

File	Description
ssx	Agent-friendly CLI for the SlopSearX API
.github/workflows/ci.yml	Main CI: lint + test on push/PR
.github/workflows/docker.yml	Docker build and push to ghcr.io
.github/workflows/droid.yml	Factory Droid tagging workflow
.github/workflows/droid-review.yml	Factory Droid PR review workflow
Dockerfile	Multi-stage production Docker build
docker-compose.yml	Local dev orchestration with Valkey
k8s/	Kubernetes deployment manifests
pyproject.toml	Build config, dependencies, and ruff settings