josty 0.9.0

Keyless search and bounded text extraction for agents and scripts.

What It Is

Josty queries public search backends in parallel through ddgs, fuses rankings with Cormack-Clarke Reciprocal Rank Fusion (RRF), canonicalizes URLs, and optionally extracts bounded page text.

It also calls Mwmbl's keyless JSON search API directly. ddgs has no Mwmbl engine, so this one source is a native adapter: still one bounded call per query variant, still no key. It is a fallback: its rows are fused only when every other engine returned nothing, because fused as an equal voter it can displace results the primary engines ranked higher, and an empty run is already reported as status: "empty" for the caller to act on. It takes only a query, so a run with --time-limit or --region reports the source as skipped rather than returning results that ignore the filter, and --safe-search on skips it too (see the skill's option table for which engines apply that hint at all).

It is designed for AI agents and developer scripts that need a self-contained search step without API keys, background daemons, or browser engines.

┌──────────────────────────────┐
│  Local Agent / Script Step   │
└──────────────┬───────────────┘
               │ single search execution
               ▼
┌──────────────────────────────┐
│            Josty             │
│  - Bounded parallel fanout   │
│  - Domain-weighted RRF (k=60)│
│  - In-process breaker & cache│
│  - Trafilatura text extract  │
└──────────────┬───────────────┘
               │
               ▼
┌──────────────────────────────┐
│  Public Backends             │
│  via ddgs: Brave,DuckDuckGo, │
│   Yahoo, Mojeek, Startpage,  │
│   Google                     │
│  native: Mwmbl (keyless JSON)│
└──────────────────────────────┘

Installation

# Run instantly with uvx (no install step needed):
uvx josty "Python 3.13 features" --limit 5

# Or install globally:
uv tool install josty
# or: pipx install josty

Quickstart

# 1. Basic search (returns top 5 results):
josty "Python 3.13 release highlights" --limit 5

# 2. Boost technical documentation domains (dev profile):
josty "FastAPI dependency injection" --profile dev --limit 5

# 3. Restrict search to specific domains (up to 5):
josty "httpx connection pool timeout" --site github.com --site python-httpx.org

# 4. Extract bounded Markdown page text from top results:
josty "RRF rank fusion algorithm" --limit 3 --fetch

# 5. Unix pipeline (stream search results straight into fetch):
josty search "FastAPI dependency injection" --limit 3 | josty fetch --stdin

Output & Status Contract

Normal searches emit one JSON document on stdout. Diagnostics and warnings route strictly to stderr.

{
  "schema_version": "1.0",
  "query": "FastAPI dependency injection",
  "status": "complete",
  "count": 3,
  "partial": false,
  "cached": false,
  "provider_count": 7,
  "nonempty_provider_count": 2,
  "coverage": 0.286,
  "providers": [...],
  "results": [
    {
      "title": "Dependencies - FastAPI",
      "url": "https://fastapi.tiangolo.com/tutorial/dependencies/",
      "snippet": "FastAPI has a very powerful but intuitive Dependency Injection system...",
      "sources": ["duckduckgo", "brave"],
      "score": 0.039024,
      "content": null
    }
  ]
}

Status Values & Exit Codes

Limitations & Non-Goals

• No Privacy or Anonymity Guarantees: Josty does not proxy or anonymize traffic. Queries are sent directly to upstream search engines.
• Best-Effort Availability: Upstream public engines may throttle (HTTP 429), present anti-bot challenges, or change response formats. Josty isolates failures via circuit breakers and surfaces errors honestly rather than hiding them behind infinite retries.
• Not a Search Engine: Josty does not maintain an index or crawl the web. It is a lightweight client adapter over ddgs and Mwmbl's public search API.
• No Hidden Query Rewriting: If a search returns empty, Josty reports status: "empty". The caller decides whether to broaden terms or adjust site filters.

Documentation

• Agent Tool Specification: .agents/skills/josty/SKILL.md (full flag specifications, schemas, provider telemetry, and agent research rules).
• Coding Agent Guide: AGENTS.md (invariants, test commands, and module layout for agents working on this codebase).
• Security Policy: SECURITY.md.