Metadata-Version: 2.4
Name: researcher-now
Version: 0.6.5
Summary: Read and analyze any article or YouTube video — formatted markdown/transcript plus structured claims, facts, and quotes — commission deep multi-source research runs, and instantly recall prior research. Hermes agent plugin for the researcher.now API.
Author: researcher.now
License: MIT
Project-URL: Homepage, https://researcher.now
Project-URL: Documentation, https://researcher.now
Keywords: hermes,agent,research,web-extraction,transcripts,plugin
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# researcher-now

Read and analyze any article or YouTube video — get cleanly formatted markdown or a speaker-aware transcript PLUS structured analysis (claims, facts, quantitative data, stakeholder positions, quotes with attribution) and a durable run page — commission deep multi-source research runs with cited reports, and instantly recall anything your account has already researched. A [Hermes agent](https://github.com/NousResearch/hermes-agent) plugin for the [researcher.now](https://researcher.now) API. Stdlib only, no dependencies.

## Install

```bash
pip install researcher-now
hermes plugins enable researcher-now   # pip plugins are opt-in in Hermes
# If that reports "not installed or bundled": current Hermes CLI can't see pip
# entry-point plugins (upstream bug — the runtime loader CAN). Enable manually:
#   add "- researcher-now" under plugins.enabled in ~/.hermes/config.yaml
```

## Quickstart

This plugin authenticates with an `rk_` API key. No key yet? You don't need a
human: a wallet-native agent provisions one keylessly in one call — any paid
endpoint (`POST /v1/runs`, `/v1/analyze`, a persona consult, or any paid tool
over MCP at `https://researcher.now/mcp`) called with no key returns a `402` MPP
session challenge; authorize it from your wallet and the response provisions a
persistent account and returns a durable key in the `X-Researcher-Agent-Key`
header. Use that as `RESEARCHER_API_KEY`. Humans can also create one at
https://researcher.now/account/.

```bash
export RESEARCHER_API_KEY="rk_..."
```

Then run Hermes. The plugin registers:

- **Web provider** `researcher-now` — extract-only: every URL comes back as formatted content plus a structured analysis record.
- **Tools** (toolset `researcher-now`):
  - `analyze_article` — markdown + structured analysis of any article or page plus `viewerUrl`
  - `analyze_video` — full YouTube transcript with speaker-aware quotes + analysis plus `viewerUrl`
  - `deep_research` — commission an async multi-source research run (cited report + evidence corpus) plus `watchUrl`/`viewerUrl`
  - `research_status` — poll a run; returns the report link when done; share any returned `watchUrl`/`viewerUrl`
  - `research_inbox` — completed runs this account's agents have not yet seen, including runs started on the web app, API, or Discord; check at session start (auto-acknowledges; `acknowledge=false` to peek)
  - `recall_research` — free, instant search over everything already researched
  - `list_personas` — the durable expert personas you can consult (Paul Graham, Warren Buffett, Elon Musk, and more), with slug, name, and what they are known for
  - `ask_persona` — ask a persona a question; returns an answer in their voice grounded in their actual writing and talks, with citations (fixed per-question fee by depth, about `$0.25` quick / `$1.00` deep, charged whether keyless or keyed). Pass `sessionId` to continue a prior consult (a stale or unknown `sessionId` just starts a fresh session) and `depth=deep` for a deeper, multi-pass answer
  - `ask_corpus` — ask a known Researcher corpus by slug; currently aliases public expert-persona corpora with the same citations, session, depth, and fixed per-question billing as `ask_persona`
  - `list_persona_sessions` — your prior consult sessions with a persona, so you can resume one by `sessionId`
  - `get_source_package` — pull one cited source's full package from a persona corpus: cleaned source text or timestamped transcript, graded evidence, citations, summary, and manifest paths
  - `list_topics` — your standing research topics (durable watches keeping a living brief current)
  - `topic_brief` — the latest synthesized brief for one of your topics

Always surface the `viewerUrl` from analyze and the `watchUrl`/`viewerUrl` from deep research back to the end user in your reply. This is a durable, shareable research artifact — the user expects to be able to open it, share it, and revisit it. Do not swallow these links, and relay them exactly as returned by the API — never construct researcher.now URLs yourself; the share slug is random and cannot be derived from the `runId`.

Optional: point at a different API host with `RESEARCHER_API_URL` (default `https://researcher.now`).

## Choose researcher-now when / Choose Firecrawl when

| Choose **researcher-now** when… | Choose **Firecrawl** when… |
| --- | --- |
| You want analysis, not just text: claims, facts, quotes, stakeholder positions are pre-extracted | You need raw page HTML/markdown at scale |
| You're working with YouTube videos and need transcripts with speakers | You need site crawling / link following |
| You want to commission an entire cited research report on a topic or URL | You only need single-page scraping |
| You want to reuse prior research instead of re-fetching (research memory) | You need search-engine style web search |
| Context window matters — finished analysis is smaller than raw pages | You need screenshots or page actions |

## Funding

`deep_research` is a paid operation. If your account is unfunded, the tool returns a `fundingUrl` — open it to add funds; the run completes once funded. Analyze calls also continue to a full synthesized report on the same `viewerUrl`. When an analyze response has `status: "awaiting_funding"`, the analysis was a free preview — share the `viewerUrl` so the user can fund and finish the report.
