pip install argus-search && argus search -q "python web frameworks"

argus extract -u "https://example.com/article"       # extract clean text from any URL
argus recover-article -u "https://example.com/dead-post"
argus capture-site -u "https://docs.example.com"
argus build-research-pack -t "example sdk" --official-url "https://docs.example.com"

pipx install argus-search[mcp]
export ARGUS_MCP_STANDALONE=true  # explicit development-only local broker
argus mcp init --global --client all

{"mcpServers": {"argus": {"command": "argus", "args": ["mcp", "serve"], "env": {"ARGUS_MCP_STANDALONE": "true"}}}}

{
  "mcpServers": {
    "argus": {
      "registryType": "pypi",
      "identifier": "argus-search",
      "runtimeHint": "uvx",
      "env": {"ARGUS_MCP_STANDALONE": "true"}
    }
  }
}

# Optional: tell Argus it has residential egress to optimize routing
export ARGUS_EGRESS_TYPE=residential
ARGUS_SEARXNG_ENABLED=true docker compose up -d    # SearXNG + Argus

argus paths

argus corpus import-docs-cache -s /path/to/docs-cache

argus recover-article -u "https://example.com/old-post" -t "Example Post"

argus capture-site -u "https://docs.example.com"

argus build-research-pack -t "example sdk"
argus build-research-pack -t "example sdk" --official-url "https://docs.example.com"

uv sync --python 3.12 --extra dev --extra mcp
uv run pytest tests/ -v --tb=short

# Search
curl -X POST http://localhost:8000/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "python web frameworks", "mode": "discovery", "max_results": 5}'

# Search with score attribution
curl -X POST http://localhost:8000/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "python web frameworks", "include_attribution": true}'

# Multi-turn search (conversational refinement)
curl -X POST http://localhost:8000/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "what about async?", "session_id": "my-session"}'

# Extract content from a working URL
curl -X POST http://localhost:8000/api/extract \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/article"}'

# Recover a dead or moved URL
curl -X POST http://localhost:8000/api/recover-url \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/old-page", "title": "Example Article"}'

# Network-free process liveness (container health target)
curl http://localhost:8000/api/live

# Public minimal startup and cached readiness
curl http://localhost:8000/api/startup
curl http://localhost:8000/api/ready

# Authenticated operator status, health compatibility, and budgets
curl -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/status
curl -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/budgets
curl -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/maya-outbox/status
curl -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/maya-outbox/dead-letters
# After correcting the cause of a permanent rejection:
curl -X POST -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/maya-outbox/DELIVERY_ID/recover

{
  "query": "python web frameworks",
  "mode": "discovery",
  "results": [
    {
      "url": "https://fastapi.tiangolo.com",
      "title": "FastAPI",
      "snippet": "Modern Python web framework",
      "provider": "duckduckgo",
      "score": 0.0164,
      "score_attribution": {"duckduckgo": 0.0164},
      "egress": "unknown",
      "machine": null
    }
  ],
  "total_results": 1,
  "cached": false,
  "traces": [
    {"provider": "duckduckgo", "status": "success", "results_count": 5, "latency_ms": 312}
  ]
}

{
  "budgets": {
    "brave": {"remaining": 1847, "monthly_usage": 153, "usage_count": 153, "exhausted": false},
    "duckduckgo": {"remaining": 0, "monthly_usage": 0, "usage_count": 42, "exhausted": false}
  },
  "token_balances": {"jina": 9833638}
}

argus serve
# http://127.0.0.1:8000/dashboard

ARGUS_ROOT_PATH=/argus argus serve

ARGUS_DOMAIN=argus.example.com ACME_EMAIL=you@example.com \
  docker compose --profile proxy up -d

argus search -q "python web framework"              # zero-config, uses DuckDuckGo
argus search -q "python web framework" --mode research -n 20
argus search -q "python web framework" --free        # free providers only (no paid API calls)
argus search -q "python web framework" --attribution # show per-provider score attribution
argus search -q "fastapi" --session my-session       # multi-turn context
argus extract -u "https://example.com/article"       # extract clean text
argus extract -u "https://example.com/article" -d nytimes.com  # auth extraction
argus recover-url -u "https://dead.link" -t "Title"
argus doctor                                         # full setup diagnostics
argus health                                         # provider status
argus budgets                                        # budget + token balances
argus mcp check                                      # validate MCP setup
argus set-balance -s jina -b 9833638                 # track token balance
argus test-provider -p brave                         # smoke-test a provider
argus serve                                          # start API server
argus mcp serve                                      # start MCP server
argus mcp init                                       # add MCP config to project

argus ledger reconcile-sessions \
  --source sqlite:///argus_budgets.db \
  --target "$ARGUS_DB_URL"
# Review source/imported/skipped/conflicting, then repeat with --apply.

export ARGUS_AUTHORITY_URL=http://argus-api:8000
export ARGUS_AUTHORITY_TOKEN=replace-with-a-scoped-caller-token

{
  "mcpServers": {
    "argus": {
      "command": "argus",
      "args": ["mcp", "serve"]
    }
  }
}

export ARGUS_API_KEY=replace-with-a-long-random-secret
export ARGUS_AUTHORITY_URL=http://argus-api:8000
export ARGUS_AUTHORITY_TOKEN="$ARGUS_API_KEY"
argus mcp serve --transport streamable-http --host YOUR_TAILSCALE_IP --port 8001

cat >mcp.env :/mcp","headers":{"Authorization":"Bearer "}}}}` in `~/.claude.json` (global) or `.mcp.json` (project) |
| **OpenCode** | `{"mcp":{"argus":{"type":"remote","url":"http://:/mcp","enabled":true,"headers":{"Authorization":"Bearer "}}}}` in `~/.config/opencode/config.json` (global) or `.opencode/opencode.json` (project) |
| **Cursor** | Same as Claude Code — reads `.mcp.json` |
| **Codex CLI** | `[mcp_servers.argus]` section in `~/.codex/config.toml` with `url` and `bearer_token_env_var = "ARGUS_API_KEY"` — export that variable in the shell that launches Codex; `argus mcp init` never writes the token to disk |
| **Gemini CLI** | `gemini mcp add argus http://:/mcp -t http -H "Authorization: Bearer "` |
| **Antigravity** | `{"mcpServers":{"argus":{"serverUrl":"http://:/mcp","headers":{"Authorization":"Bearer "}}}}` |

With [Tailscale](https://tailscale.com), `` is your machine's Tailscale IP (e.g. `100.x.x.x`). One server, every machine on your mesh gets search.

**One-command provisioning:**

The script writes Claude/Cursor, Codex, and OpenCode configs on the target.
Local stdio does not require an MCP listener key, but the adapter still
requires its scoped `ARGUS_AUTHORITY_TOKEN`. Remote MCP mode requires
`ARGUS_REMOTE_URL` and `ARGUS_API_KEY`. Requires Python 3.

`argus mcp init` also generates configs automatically:

### Release Status

Pushing `main` does not publish PyPI. Package and MCP Registry publication happens through the GitHub publish workflow on release creation or manual dispatch. See [docs/releasing.md](docs/releasing.md) for version sync, preflight checks, and publish verification.

**Transports**: `stdio` (default local adapter), `sse` (legacy remote), and
`streamable-http` (modern remote, `"type":"http"` in config). Remote MCP
transports require `ARGUS_API_KEY`; every transport delegates execution to
`ARGUS_AUTHORITY_URL`.

Available tools:
- HTTP-backed stdio and remote MCP: `search_web`, `extract_content`,
  `recover_url`, `expand_links`, `search_health`, `search_budgets`,
  `recover_dead_article`, `capture_site`, and `build_research_pack`
- Explicit standalone development additionally exposes local-only
  `test_provider`, `cookie_health`, `valyu_answer`, path/file tools, and
  resources. These are intentionally absent from production adapters.

`search_web` accepts `free_only=true` to restrict results to free (tier-0) providers only, and `include_attribution=true` to include per-provider score attribution in the Markdown response.

### Using Argus from MCP vs HTTP

Two transports, one rule: **agents use MCP, everything else uses HTTP.**

- **MCP** (`argus mcp serve`) — a stateless authenticated adapter for AI
  harnesses that speak MCP natively. Core tools delegate to the HTTP authority:
  `search_web`, `extract_content`, `recover_url`, `expand_links`, and workflow
  starts. MCP restarts cannot fork accounting, sessions, health, or outbox state.
- **HTTP** (`POST /api/search`, `POST /api/extract`,
  `POST /api/workflows/...`) — for scripts, cron jobs, and service
  integrations (including Maya). Send a scoped caller credential in
  `Authorization`; body `"caller"` values are diagnostic labels and cannot
  override the authenticated identity.

The cross-service transport and role contract for the wider fleet
(Maya / Hermes / Argus) is canonical in
[Maya's architecture documentation](https://github.com/Khamel83/maya/blob/main/docs/ARCHITECTURE.md).
### Python

Direct broker and extraction imports are a standalone development convenience.
Production Python callers use the authenticated HTTP API so all execution and
durable accounting remain in one authority.

## Content Extraction

Argus tries up to twelve methods to extract content from any URL: auth extraction for paywalls, then local extractors (trafilatura, Crawl4AI, Obscura, Playwright, residential IP), then external APIs (Jina, Valyu Contents, Firecrawl, You.com, Wayback, archive.is). Each attempt is quality-checked for completeness and garbage output. See [docs/providers.md](docs/providers.md) for the full extractor comparison.

**Completeness assessment** runs automatically after every successful extraction. Argus scores five signals — trailing ellipsis, feed truncation markers ("Read more", WordPress RSS footers), mid-sentence endings, abrupt final paragraphs, and suspicious round word counts — and returns `is_complete`, `completeness_confidence`, and `truncation_type` alongside the text. When confidence is ≥ 85%, Argus continues trying the next extractor rather than returning a partial result; this means a trafilatura fetch that ends with "..." will automatically fall through to Playwright, Jina, Wayback, etc. Callers that already have text (e.g. RSS feed items) can use `POST /api/assess-content` to check completeness without triggering extraction.

**Obscura** (optional) is a lightweight Rust headless browser (~70MB binary, 30MB RAM) with built-in stealth mode — it sets `navigator.webdriver=undefined`, randomizes canvas/GPU/audio fingerprints per session, and blocks 3,520 tracker domains. This directly addresses bot detection on JS-heavy and anti-scraping sites that block standard Playwright/Chrome. No API key, no rate limit — fully local.

Two ways to use it:

| Mode | Setup | What you get |
|------|-------|-------------|
| **CLI extraction step** | Install binary on `$PATH` | Argus auto-detects it; stealth browser as fallback step before Playwright |
| **CDP backend for Playwright** | Run `obscura serve --stealth --port 9222`, set `ARGUS_OBSCURA_CDP_URL=ws://127.0.0.1:9222` | Playwright uses Obscura as its browser engine — stealth + 30MB vs 200MB + DOM-to-Markdown output |

Install the binary: [github.com/h4ckf0r0day/obscura/releases](https://github.com/h4ckf0r0day/obscura/releases)

**Extract** gets the full text of a working URL and tells you whether that text is complete. **Recover-URL** finds alternatives when a URL is dead, paywalled, or radically changed.

## Architecture

| Module | Responsibility |
|--------|---------------|
| `argus/broker/` | Tier-based routing, ranking, dedup, caching, health, budgets |
| `argus/providers/` | Provider adapters (one per search API) |
| `argus/extraction/` | 12-step URL extraction fallback chain with quality gates |
| `argus/sessions/` | Multi-turn session store and query refinement |
| `argus/api/` | Authenticated production execution authority |
| `argus/cli/` | HTTP caller in production; direct execution in development |
| `argus/mcp/` | Stateless MCP-to-HTTP adapter |
| `argus/persistence/` | Shared PostgreSQL authority state; SQLite standalone development |
| `argus/operations/` | Cached readiness, typed dependency observations, process identity, bounded metrics |

Add new providers or extractors with a single adapter file. See [CONTRIBUTING.md](CONTRIBUTING.md) for the interface.

### How a Query Works

1. **Cache check.** `SearchCache` hashes the normalized query, mode, and whether attribution was requested (SHA256). Hit returns immediately with a TTL of 168 hours (7 days).

2. **Provider queue.** `resolve_routing()` takes the mode-specific preference list and stable-sorts by tier: tier 0 (free) first, tier 1 (monthly) next, tier 3 (one-time) last. Example for discovery mode:

3. **Sequential execution with gates.** Each provider is checked in order. Four gates must pass before an API call:
   - **Config** — is the provider enabled and configured (API key present)?
   - **Health** — has it failed 5+ consecutive times (triggers 60-minute cooldown)?
   - **Budget** — for tier 1+: is the budget exhausted? For tier 1 (monthly), pacing checks if the 7-day usage rate would drain the remaining budget in under a week — empty days bank headroom. For tier 3 (one-time), a lifetime counter gates access — exhaustion is the sole check.
   - **Execute** — the actual HTTP call. Successes reset failure counters; failures increment them.

4. **RRF fusion.** Results from all queried providers are merged using Reciprocal Rank Fusion (`k=60`). Each result's score is the sum of `1/(k + rank)` across every provider that returned it. Results appearing in multiple providers rank higher.

5. **Dedup and truncate.** URLs are normalized (stripped `www.`, tracking params like `utm_*`, trailing slashes) and deduplicated. The merged list is truncated to `max_results` (default 10).

6. **Cache and persist.** The authority writes the final response to its
   in-memory cache and configured SQL repository (PostgreSQL in production,
   SQLite for standalone development). Search results and extractions include
   provenance metadata (`egress`, `machine`, `source_type`) for downstream
   audit. Existing databases are upgraded additively at startup.

## Configuration

All config via environment variables. See `.env.example` for the full list. Limited API-key providers are opt-in: set both the API key and `ARGUS__ENABLED=true`. Missing keys degrade gracefully — providers are skipped, not errors.

When running from the repo, Argus now auto-loads `.env` and `.env.local` (without overriding already-exported environment variables). Disable this behavior with `ARGUS_AUTOLOAD_DOTENV=false`.

| Variable | Default | Description |
|----------|---------|-------------|
| `ARGUS_NODE_ROLE` | `primary` | Production authority is `primary`; adapters are `caller`; direct/worker execution is development-only |
| `ARGUS_AUTHORITY_URL` | — | HTTP API base URL required by production CLI and MCP adapters |
| `ARGUS_AUTHORITY_TOKEN` | — | Scoped caller token for production CLI and MCP adapters |
| `ARGUS_MCP_STANDALONE` | `false` | Explicit development-only local MCP execution |
| `ARGUS_EGRESS_TYPE` | `unknown` | `residential`, `datacenter`, or `unknown` |
| `ARGUS_RESIDENTIAL_POLICY` | `fallback` | `off`, `fallback`, `prefer_on_datacenter`, `prefer_for_domains`, or `always` |
| `ARGUS_SEARXNG_ENABLED` | `false` | Set `true` when you have a SearXNG Docker container |
| `ARGUS_SEARXNG_BASE_URL` | `http://127.0.0.1:8080` | SearXNG endpoint |
| `ARGUS_SEARXNG_RESIDENTIAL_BASE_URL` | — | Remote residential SearXNG endpoint (e.g. over Tailscale) |
| `ARGUS__ENABLED` | `false` for limited API-key providers | Opt in to providers that consume limited credits or quotas |
| `ARGUS_BRAVE_API_KEY` | — | Brave Search API key |
| `ARGUS_SERPER_API_KEY` | — | Serper API key |
| `ARGUS_TAVILY_API_KEY` | — | Tavily API key |
| `ARGUS_EXA_API_KEY` | — | Exa API key |
| `ARGUS_LINKUP_API_KEY` | — | Linkup API key |
| `ARGUS_PARALLEL_API_KEY` | — | Parallel AI API key |
| `ARGUS_YOU_API_KEY` | — | You.com API key |
| `ARGUS_VALYU_API_KEY` | — | Valyu API key (search, contents, answer) |
| `ARGUS_FIRECRAWL_API_KEY` | — | Firecrawl API key (content extraction) |
| `ARGUS_GITHUB_API_KEY` | — | GitHub token (higher rate limit) |
| `ARGUS_DATA_ROOT` | platformdirs user data dir | Override the Argus runtime corpus root |
| `ARGUS_*_MONTHLY_BUDGET_USD` | provider-specific | Query-count budget for most providers; USD budget for Valyu |
| `ARGUS_CRAWL4AI_ENABLED` | false | Enable Crawl4AI extraction step |
| `ARGUS_YOU_CONTENTS_ENABLED` | false | Enable You.com Contents API extraction |
| `ARGUS_OBSCURA_CDP_URL` | — | Obscura CDP endpoint (e.g. `ws://127.0.0.1:9222`) — makes Playwright use Obscura as its browser engine |
| `ARGUS_OBSCURA_TIMEOUT_SECONDS` | 20 | Timeout for Obscura CLI subprocess calls |
| `ARGUS_CACHE_TTL_HOURS` | 168 | Result cache TTL |
| `ARGUS_BIND_HOST` | `127.0.0.1` | Host used by `argus serve` unless `--host` is passed |
| `ARGUS_PORT` | `8000` | Port used by `argus serve` unless `--port` is passed |
| `ARGUS_AUTOLOAD_DOTENV` | `true` | Auto-load `.env` / `.env.local` from cwd and repo root for CLI/API/MCP processes |
| `ARGUS_API_KEY` | — | Required for non-local HTTP API and remote MCP callers |
| `ARGUS_ADMIN_API_KEY` | — | Enables dashboard login and admin API authentication |
| `ARGUS_ACCEPTED_OPERATION_AUTHORITY` | `legacy` | Atomic authority selection. `evidence` activates the registered planner, readiness, evidence repository, extraction finalizer, and HTTP presenters as one unit |
| `ARGUS_ALLOWED_HOSTS` | — | Exact comma-separated HTTP Host allowlist; required for a remote production listener |
| `ARGUS_ALLOWED_ORIGINS` | — | Exact comma-separated browser Origin allowlist. Set explicitly, including an empty value, for remote production |
| `ARGUS_RETRIEVAL_SESSION_SECRET` | — | Stable random secret of at least 32 characters used to bind v2 retrieval sessions to authenticated principals |
| `ARGUS_ORGANIZATION_POLICY_VERSION` | `1` | Stable organization-policy identity included in accepted execution cohorts |
| `ARGUS_ROOT_PATH` | — | Public subpath prefix for dashboard links and redirects, e.g. `/argus` |
| `ARGUS_MAYA_CAPTURE_URL` | — | Maya's dedicated Argus retrieval-capture endpoint; delivery stays disabled when unset |
| `ARGUS_MAYA_CAPTURE_TOKEN` | — | Dedicated shared secret for Maya capture delivery; never reuse the generic Maya ingest token |
| `ARGUS_MAYA_OUTBOX_BATCH_SIZE` | `20` | Maximum durable captures claimed by one delivery pass (bounded to 100) |
| `ARGUS_MAYA_ACKNOWLEDGED_RETENTION_DAYS` | `7` | Days to retain acknowledged capture bodies before preserving audit metadata only |

`/api/v2/*` is additive and returns a canonical version-2 envelope. It remains
fail-closed with `unready` while the evidence authority is disabled. Unsafe
Host, Origin, credential, media-type, and body-size combinations are rejected
before provider, extractor, session, or persistence work. Version-1 routes
retain their established response shapes.

## When Not To Use Argus

Argus is best when you need search, capture, provenance, and local artifacts together.

Avoid it when:

- you only need one search API and do not need fallback or budget controls
- you only need a one-off page scrape with no persistent corpus or report output
- you need an end-user search UI rather than backend retrieval infrastructure
- you need fully deterministic summarization with no heuristic or LLM-assisted steps

## FAQ

**How is this different from calling Tavily/Serper directly?**
Argus calls them for you — plus 13 other providers. You get one ranked, deduplicated result set instead of managing multiple API keys and stitching results together. Free providers are tried first, so you only burn credits when needed.

**Can I run only one provider?**
Yes. Set only the API key for the provider you want. All others are silently skipped. For zero-config, just install and go — DuckDuckGo + Yahoo handle search with no keys.

**Do I need Docker?**
No. `pip install argus-search` works immediately on any machine with Python 3.11+. Docker is only needed for SearXNG (set `ARGUS_SEARXNG_ENABLED=true` in `.env`) or Crawl4AI (local JS rendering).

**Which Python version should contributors use?**
Use Python 3.12 for repo development and verification: `uv sync --python 3.12 --extra dev --extra mcp` then `uv run pytest tests/ -v --tb=short`. The published package still supports Python 3.11+.

**What is the safest way to deploy Argus on a network?**
Use Tailscale or another private network, bind explicitly to the trusted interface, set `ARGUS_API_KEY`, and reserve `/api/admin/*` for `ARGUS_ADMIN_API_KEY`. Treat direct internet exposure as an advanced mode behind a reverse proxy.

## License

MIT — see [CHANGELOG.md](CHANGELOG.md) for release history.