Metadata-Version: 2.4
Name: p53-courier
Version: 0.1.0
Summary: CLI-based AI assisted web search with configurable breadth and depth
Author: Point 53, LLC
License-Expression: MPL-2.0
License-File: LICENSE
License-File: NOTICE
License-File: THIRD_PARTY_LICENSES.md
Keywords: ai,local-llm,ollama,point53,research,search,web
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.10
Requires-Dist: click>=8.3.1
Requires-Dist: dateparser>=1.2.2
Requires-Dist: feedparser>=6.0.12
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: ollama>=0.6.1
Requires-Dist: p53-collector
Requires-Dist: platformdirs>=4.0
Requires-Dist: protobuf>=6.33.2
Requires-Dist: pydantic>=2.0
Requires-Dist: selenium>=4.39.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: webdriver-manager>=4.0.2
Provides-Extra: all
Requires-Dist: anthropic>=0.75.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.75.0; extra == 'anthropic'
Description-Content-Type: text/markdown

# Point 53 Courier

**Your question. The open web. A cited answer.**

Point 53 Courier is a CLI-based AI-assisted web search tool — part of the Point 53 suite. You give it a query, a *breadth* (how many links per layer) and a *depth* (how many layers to follow), and Courier navigates the open web, scrapes and summarizes each source with local AI, and returns a cited transcript alongside an LLM-written report. It runs local-first: your queries and the harvested content stay on your machine unless you choose a cloud model.

> **License:** [Mozilla Public License 2.0](https://mozilla.org/MPL/2.0/) — see `LICENSE`, `NOTICE`, and `THIRD_PARTY_LICENSES.md`.

## Why Courier

A single search-engine query gives you ten blue links and no synthesis. Courier turns a query into structured, multi-layer research:

- **Local-first AI**: curation, summarization, and analysis run on your hardware via [Ollama](https://ollama.com). Switch to Anthropic or any OpenAI-compatible endpoint when you choose to — with a cloud-usage warning when content leaves your machine.
- **Breadth and depth you control**: `--breadth` sets links per layer; `--depth` sets how many layers deep Courier follows links from each page. Start shallow, go deeper when a topic warrants it.
- **Cited, greppable output**: every run is a directory of Markdown + JSONL — a human-readable `report.md`, a per-source `transcript.md`, and a machine-readable `sources.jsonl`.
- **Targeted lens**: `--target` focuses curation, summarization, and analysis toward exactly what you're after.
- **Agent-ready**: ships an MCP server and a Skill, so agents can run research through the same engine you do.

## How it works

```
query ─▶ search engine ─▶ LLM curates top --breadth links into RSS
                                  │
                                  ▼
                    scrape + summarize each source (local AI)
                                  │
             depth > 1? ─yes─▶ follow links, curate next layer ─┐
                                  │                              │
                                  └──────────────◀──────────────┘
                                  ▼
       transcript.md + sources.jsonl ─▶ holistic LLM report ─▶ report.md
```

`--depth 2` is a reasonable default; deeper runs cost more time and more tokens.

## Install

Courier builds on **Point 53 Collector**'s scraping-and-summarization engine, which is installed automatically as a dependency — you don't install Collector separately.

```bash
# Install uv (https://docs.astral.sh/uv/) if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh                 # Linux / macOS
# powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"   # Windows

# Install Point 53 Courier as a global CLI tool
uv tool install p53-courier --index https://dist.point53.ai/simple/

# Create default config files, then verify
courier config doctor
courier doctor
```

To use a cloud (Anthropic) model, add the optional extra:

```bash
uv tool install 'p53-courier[anthropic]' --index https://dist.point53.ai/simple/
```

### Prerequisites

- **Python 3.10+** (uv manages this for you)
- **Ollama** running locally or on your network. Pull the default models:
  ```bash
  ollama pull gemma4:e4b         # summary + post-analysis
  ollama pull qwen3.5:9b         # chat
  ollama pull qwen2.5-coder:14b  # search-result links → RSS (see models.toml note)
  ```
- **Firefox** installed — the default scraping browser. Selenium drives a separate instance, so defaulting to Firefox keeps scraping clear of your everyday Chrome profile. Chrome is configurable in `courier.toml`.

## Usage

```bash
# Broad search — default breadth (5 links) and depth (1 layer)
courier search "open-source LLMs"

# Focused search with a target lens
courier search "open-source LLMs" --target "new open-weight model releases and benchmarks"

# Go deeper and wider, then ask a secondary question of the findings
courier search "AI agent frameworks" --target "compare capabilities" \
  --analysis-prompt "which is best for a small team under 50 people?" --breadth 10 --depth 2

# Different breadth after the first layer
courier search "local inference" --target "setup guides" --breadth 8 --breadth-n 3 --depth 3

# Interactive chat with the report as context
courier search "running models on a laptop" --target "step by step" --chat

# Read and analyze a single URL
courier url "https://docs.vllm.ai/en/latest/" --target "serving and quantization"

# Fully headless for cron / automation; print to stdout
courier search "this week in open models" --full-headless --stdout-only | tee research.txt

# Rebuild the derived index from run output
courier reindex
```

### Commands

```
courier search "<query>" [flags]   research a query through the configured search engine
courier url <url> [flags]          extract and analyze links from a single URL
courier doctor                     health checks (config, storage, model, Collector, webdriver)
courier config validate            validate config against the Pydantic schema
courier config doctor              validate + create missing config files with defaults
courier reindex                    rebuild courier.db from run output
courier serve-mcp                  stdio MCP server for agents
```

### Flags (search / url)

| Flag | Purpose |
| --- | --- |
| `--target` | Focus lens for curation, summarization, and analysis (recommended with `url`) |
| `--analysis-prompt` | Secondary analysis question asked of the finished transcript + summary |
| `--breadth` | Links per depth layer (default from config) |
| `--breadth-n` | Override breadth for layers after the first |
| `--depth` | Number of depth layers (default from config) |
| `--chat` / `--chat-prompt` | Open an interactive chat with the report as context (`--chat-prompt` seeds the first question) |
| `--headless` | Run the summarization browser headless (search / navigation stays visible) |
| `--full-headless` | Run every browser headless (may trip bot detection on search pages) |
| `--stdout-only` | Print to stdout; skip file output and the index |
| `--i-understand-the-risks` | Suppress cloud-model usage warnings for the run |

## Configuration

Two TOML files under `~/.config/point53/courier/` — run `courier config doctor` to create them with defaults:

- **`courier.toml`** — operational settings: default search engine, breadth/depth defaults, browser/webdriver options, and the `[collector.*]` passthrough that overrides Collector's scraping behavior for Courier's runs.
- **`models.toml`** — per-role LLM config (`provider`, `model`, `base_url`, optional `api_key`) for curation, summarization, and chat. Each role independently selects `ollama`, `anthropic`, or `openai-compatible`.

API keys resolve **env-first** (file-last): `P53_<PROVIDER>_API_KEY` > vendor env (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`) > the literal `api_key` in `models.toml`. Routing any role to a non-local `base_url` prints a cloud-usage warning — suppress with `--i-understand-the-risks` or in config.

## Output

Each run is a self-describing directory under `~/.local/share/point53/courier/runs/<timestamp>_<slug>/`:

| File | Contents |
| --- | --- |
| `report.md` | Holistic LLM summary, plus an optional `## Post-Analysis` section |
| `transcript.md` | Per-source summaries (from Collector's distill) |
| `sources.jsonl` | One JSON object per source — the machine-readable record |
| `feed-1.xml`, `feed-2.xml`, … | Curated RSS for each depth layer |
| `manifest.json` | Suite v1 manifest (`type: "courier-run"`, `ingestable_by`, plus enterprise-coordination fields) |

The Markdown is the source of truth; `courier.db` is a derived index, rebuildable any time with `courier reindex`.

## Agent surface

- **MCP** — `courier serve-mcp` exposes `search` and `url` as stdio MCP tools, with schemas auto-derived from the same Pydantic models as the CLI.
- **Skill** — `src/p53_courier/skills/courier/SKILL.md` for agent runtimes without MCP.

## The Suite

Point 53 Courier is one of six tools in the Point 53 Suite:

| Tool | Purpose |
| --- | --- |
| **Point 53 Collector** | RSS/web aggregation, AI-summarized Markdown briefings |
| **Point 53 Courier** | Headless/non-headless search agent with configurable depth and scope |
| **Point 53 Intercept** | Desktop + mic audio capture, transcription, and structured notes |
| **Point 53 Handler** | Orchestrator + REPL/TUI + optional web UI; aggregates MCP servers |
| **Point 53 Nightdesk** | Iterative overnight autoresearch engine with pluggable backends |
| **Point 53 Monitor** | iOS/Android call screener (coming soon) |

All tools are written in Python and released under the Mozilla Public License 2.0.

## License and Attribution

- **Point 53 Courier source code:** Mozilla Public License, v. 2.0 — see `LICENSE`.
- **Third-party runtime dependencies and external tools:** see `NOTICE` for a summary and `THIRD_PARTY_LICENSES.md` for full attribution.
- **Ollama and Anthropic models:** not distributed with Courier; each carries its own license from its respective publisher.
- **Trademarks:** "Point 53" and "Point 53 Courier" are trademarks of Point 53, LLC. MPL-2.0 section 2.3 excludes trademark rights from the copyright/patent grant — nothing in the license authorizes use of these marks. The CLI command `courier` is a functional identifier, not a trademark claim on the generic English word.
