know-fast 0.1.0__tar.gz

know_fast-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: know-fast
+Version: 0.1.0
+Summary: ⚡️ know.fast — links in, knowledge out. Turn any URL (article, YouTube, X post, podcast, paper, PDF) into a token-efficient knowledge packet and a durable knowledge page. Flat $0.01 per link. Hermes agent plugin.
+Author: know.fast
+License: MIT
+Project-URL: Homepage, https://know.fast
+Project-URL: Documentation, https://know.fast/agent.txt
+Keywords: hermes,agent,knowledge,web-extraction,transcripts,plugin,know.fast
+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
+
+# ⚡️ know-fast
+
+**Links in, knowledge out.** Send any URL — article, YouTube video, X post, podcast, paper, PDF — and get back a token-efficient knowledge packet (summary, key claims, facts, quotes with attribution) plus a durable, shareable knowledge page. Links are unique: anything anyone has ever known answers instantly. **Every call is a flat $0.01**, first-ever video transcription included.
+
+A [Hermes agent](https://github.com/NousResearch/hermes-agent) plugin for [know.fast](https://know.fast). Stdlib only, no dependencies.
+
+## Install
+
+```bash
+pip install know-fast
+hermes plugins enable know-fast   # 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 "- know-fast" under plugins.enabled in ~/.hermes/config.yaml
+```
+
+## Quickstart
+
+The plugin authenticates with an API key. No key yet? You don't need a human:
+know.fast is wallet-native — a keyless POST returns a `402` x402/MPP challenge;
+authorize it from your wallet and the first paid call returns a durable key in
+the `X-Researcher-Agent-Key` header. Store it:
+
+```bash
+export KNOW_FAST_API_KEY="rk_..."
+```
+
+(An existing `RESEARCHER_API_KEY` also works — same account system.)
+
+Then run Hermes. The plugin registers:
+
+- **Web provider** `know-fast` — extract-only: every URL comes back as the knowledge packet, so `web_extract` costs a cent and a couple thousand tokens instead of a raw page.
+- **Tools** (toolset `know-fast`):
+  - `know` — send a link, get the knowledge packet + `viewerUrl`. Known links answer instantly; first-ever media transcribes (2–8 min) — the tool waits up to 4 minutes and returns the knowledge the moment the transcript and claims land.
+  - `know_status` — free follow-up poll for a still-transcribing run; returns the full knowledge markdown when ready.
+
+Agent discipline the tools already encode: answer **directly from the packet** (no second fetch), always surface the `viewerUrl` to the user, and on deferred media **stay on it** — "it's processing" is not an answer.
+
+Point at a different host with `KNOW_FAST_API_URL` (default `https://know.fast`).
+
+## Choose know-fast when / Choose Firecrawl when
+
+| Choose **know-fast** when… | Choose **Firecrawl** when… |
+| --- | --- |
+| You want knowledge, not markup: summary, claims, facts, quotes pre-extracted | You need raw page HTML/markdown at scale |
+| You're working with YouTube videos or podcasts and need transcripts | You need site crawling / link following |
+| Context window matters — a ~2k-token packet beats a raw page | You need screenshots or page actions |
+| You want a durable, citable page you can hand to the user | You only need throwaway scrapes |
+| You want predictable spend — flat $0.01 per link, media included | You have your own extraction pipeline |
+
+## The full contract
+
+`https://know.fast/agent.txt` is the canonical agent contract. Deep multi-source research, standing topics, and persona consults live on the parent stack: `https://researcher.now/agent.txt` (plugin: `pip install researcher-now`).

know_fast-0.1.0/README.md

@@ -0,0 +1,53 @@
+# ⚡️ know-fast
+
+**Links in, knowledge out.** Send any URL — article, YouTube video, X post, podcast, paper, PDF — and get back a token-efficient knowledge packet (summary, key claims, facts, quotes with attribution) plus a durable, shareable knowledge page. Links are unique: anything anyone has ever known answers instantly. **Every call is a flat $0.01**, first-ever video transcription included.
+
+A [Hermes agent](https://github.com/NousResearch/hermes-agent) plugin for [know.fast](https://know.fast). Stdlib only, no dependencies.
+
+## Install
+
+```bash
+pip install know-fast
+hermes plugins enable know-fast   # 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 "- know-fast" under plugins.enabled in ~/.hermes/config.yaml
+```
+
+## Quickstart
+
+The plugin authenticates with an API key. No key yet? You don't need a human:
+know.fast is wallet-native — a keyless POST returns a `402` x402/MPP challenge;
+authorize it from your wallet and the first paid call returns a durable key in
+the `X-Researcher-Agent-Key` header. Store it:
+
+```bash
+export KNOW_FAST_API_KEY="rk_..."
+```
+
+(An existing `RESEARCHER_API_KEY` also works — same account system.)
+
+Then run Hermes. The plugin registers:
+
+- **Web provider** `know-fast` — extract-only: every URL comes back as the knowledge packet, so `web_extract` costs a cent and a couple thousand tokens instead of a raw page.
+- **Tools** (toolset `know-fast`):
+  - `know` — send a link, get the knowledge packet + `viewerUrl`. Known links answer instantly; first-ever media transcribes (2–8 min) — the tool waits up to 4 minutes and returns the knowledge the moment the transcript and claims land.
+  - `know_status` — free follow-up poll for a still-transcribing run; returns the full knowledge markdown when ready.
+
+Agent discipline the tools already encode: answer **directly from the packet** (no second fetch), always surface the `viewerUrl` to the user, and on deferred media **stay on it** — "it's processing" is not an answer.
+
+Point at a different host with `KNOW_FAST_API_URL` (default `https://know.fast`).
+
+## Choose know-fast when / Choose Firecrawl when
+
+| Choose **know-fast** when… | Choose **Firecrawl** when… |
+| --- | --- |
+| You want knowledge, not markup: summary, claims, facts, quotes pre-extracted | You need raw page HTML/markdown at scale |
+| You're working with YouTube videos or podcasts and need transcripts | You need site crawling / link following |
+| Context window matters — a ~2k-token packet beats a raw page | You need screenshots or page actions |
+| You want a durable, citable page you can hand to the user | You only need throwaway scrapes |
+| You want predictable spend — flat $0.01 per link, media included | You have your own extraction pipeline |
+
+## The full contract
+
+`https://know.fast/agent.txt` is the canonical agent contract. Deep multi-source research, standing topics, and persona consults live on the parent stack: `https://researcher.now/agent.txt` (plugin: `pip install researcher-now`).

know_fast-0.1.0/know_fast/__init__.py

@@ -0,0 +1,34 @@
+"""know-fast — Hermes plugin for ⚡️ know.fast: links in, knowledge out.
+
+Send any link (article, YouTube, X post, podcast, paper, PDF) and get back a
+token-efficient knowledge packet plus a durable knowledge page. Links are
+unique — anything anyone has ever known answers instantly. Flat $0.01 per call.
+"""
+
+from __future__ import annotations
+
+import logging
+
+__version__ = "0.1.0"
+
+logger = logging.getLogger("know_fast")
+
+
+def register(ctx) -> None:
+    """Hermes plugin entry point (entry point group: hermes_agent.plugins)."""
+    from . import provider as provider_module
+
+    if not provider_module.HERMES_AVAILABLE:
+        logger.warning(
+            "know-fast: hermes-agent is not importable (module 'agent' not "
+            "found); skipping registration. Install and run inside hermes-agent "
+            "to use this plugin."
+        )
+        return
+
+    ctx.register_web_search_provider(provider_module.KnowFastProvider())
+
+    from . import tools
+
+    tools.register_tools(ctx)
+    logger.info("know-fast: registered web provider and %d tools", len(tools.TOOLS))

know_fast-0.1.0/know_fast/client.py

@@ -0,0 +1,149 @@
+"""Tiny stdlib-only JSON client for the know.fast API.
+
+No third-party dependencies: urllib + json only.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import urllib.error
+import urllib.parse
+import urllib.request
+
+DEFAULT_BASE_URL = "https://know.fast"
+CLIENT_HEADER = "knowfast-hermes-pip"
+PLUGIN_VERSION = "0.1.0"
+KEY_HINT = (
+    "Invalid or missing API key. know.fast is a flat $0.01 per link: a "
+    "wallet-native agent can pay keylessly — any POST with no key returns a "
+    "402 x402/MPP challenge; authorize it and the first paid call returns a "
+    "durable key in the X-Researcher-Agent-Key header. Store that key and "
+    "set it as the KNOW_FAST_API_KEY environment variable."
+)
+
+
+class KnowFastError(Exception):
+    """API or transport failure. Carries HTTP status (if any) and parsed body."""
+
+    def __init__(self, message: str, status: int | None = None, body: dict | None = None):
+        super().__init__(message)
+        self.status = status
+        self.body = body if isinstance(body, dict) else {}
+
+
+def base_url() -> str:
+    return os.getenv("KNOW_FAST_API_URL", DEFAULT_BASE_URL).rstrip("/")
+
+
+def api_key() -> str:
+    # know.fast runs on the researcher.now account system — the same rk_ key
+    # works on both, so fall back to an already-configured researcher key.
+    return os.getenv("KNOW_FAST_API_KEY") or os.getenv("RESEARCHER_API_KEY", "")
+
+
+def _parse_body(raw: bytes) -> dict:
+    try:
+        parsed = json.loads(raw.decode("utf-8", errors="replace"))
+        return parsed if isinstance(parsed, dict) else {"data": parsed}
+    except (ValueError, AttributeError):
+        return {}
+
+
+def _apply_contract_headers(payload: dict, headers) -> dict:
+    """Surface the API's contract stamp to the agent.
+
+    The server stamps every response with X-Researcher-Contract (the agent
+    contract version — agents re-read agent.txt when it changes) and
+    X-Researcher-Notice (time-boxed change notices). X-Researcher-Min-Plugin
+    is deliberately ignored here: it versions the researcher-now package's
+    release stream, not know-fast's.
+    """
+    contract = headers.get("X-Researcher-Contract")
+    if contract:
+        payload.setdefault("contractVersion", contract)
+    notice = headers.get("X-Researcher-Notice")
+    if notice:
+        payload.setdefault("contractNotice", notice)
+    return payload
+
+
+def _headers(body: dict | None) -> dict:
+    headers = {
+        "Accept": "application/json",
+        "X-Researcher-Client": CLIENT_HEADER,
+    }
+    key = api_key()
+    if key:
+        headers["X-Researcher-API-Key"] = key
+        headers["Authorization"] = "Bearer " + key
+    if body is not None:
+        headers["Content-Type"] = "application/json"
+    return headers
+
+
+def request(
+    method: str,
+    path: str,
+    body: dict | None = None,
+    params: dict | None = None,
+    timeout: float = 30,
+) -> tuple[int, dict]:
+    """Make a JSON request. Returns (status, payload) on 2xx.
+
+    Raises KnowFastError on HTTP errors, timeouts, and network failures.
+    """
+    url = base_url() + path
+    if params:
+        url += "?" + urllib.parse.urlencode(params)
+    data = json.dumps(body).encode("utf-8") if body is not None else None
+    req = urllib.request.Request(url, data=data, headers=_headers(body), method=method)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return resp.status, _apply_contract_headers(_parse_body(resp.read()), resp.headers)
+    except urllib.error.HTTPError as exc:
+        payload = _parse_body(exc.read())
+        message = str(payload.get("error") or payload.get("message") or "")
+        if exc.code == 401:
+            message = KEY_HINT if not message else f"{message} {KEY_HINT}"
+        elif not message:
+            message = f"know.fast API returned HTTP {exc.code}"
+        raise KnowFastError(message, status=exc.code, body=payload) from exc
+    except (TimeoutError, socket.timeout) as exc:
+        raise KnowFastError(f"Request to {url} timed out after {timeout:.0f}s") from exc
+    except urllib.error.URLError as exc:
+        reason = getattr(exc, "reason", exc)
+        if isinstance(reason, (TimeoutError, socket.timeout)):
+            raise KnowFastError(f"Request to {url} timed out after {timeout:.0f}s") from exc
+        raise KnowFastError(f"Network error reaching {url}: {reason}") from exc
+
+
+def request_text(path: str, timeout: float = 30) -> str:
+    """GET a text resource (the <slug>.md knowledge markdown)."""
+    url = base_url() + path
+    headers = {
+        "Accept": "text/markdown, text/plain, application/json",
+        "X-Researcher-Client": CLIENT_HEADER,
+    }
+    key = api_key()
+    if key:
+        headers["X-Researcher-API-Key"] = key
+        headers["Authorization"] = "Bearer " + key
+    req = urllib.request.Request(url, headers=headers, method="GET")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return resp.read().decode("utf-8", errors="replace")
+    except urllib.error.HTTPError as exc:
+        payload = _parse_body(exc.read())
+        message = str(payload.get("error") or payload.get("message") or "")
+        if not message:
+            message = f"know.fast API returned HTTP {exc.code}"
+        raise KnowFastError(message, status=exc.code, body=payload) from exc
+    except (TimeoutError, socket.timeout) as exc:
+        raise KnowFastError(f"Request to {url} timed out after {timeout:.0f}s") from exc
+    except urllib.error.URLError as exc:
+        reason = getattr(exc, "reason", exc)
+        if isinstance(reason, (TimeoutError, socket.timeout)):
+            raise KnowFastError(f"Request to {url} timed out after {timeout:.0f}s") from exc
+        raise KnowFastError(f"Network error reaching {url}: {reason}") from exc

know_fast-0.1.0/know_fast/provider.py

@@ -0,0 +1,109 @@
+"""Hermes WebSearchProvider backed by know.fast — links in, knowledge out.
+
+Extract-only provider: no search, but extract() returns the know.fast
+knowledge packet (or full knowledge markdown) for each URL.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+
+from . import client, tools
+
+logger = logging.getLogger("know_fast")
+
+try:  # Hermes installs `agent` as a top-level module.
+    from agent.web_search_provider import WebSearchProvider
+
+    HERMES_AVAILABLE = True
+except Exception:  # pragma: no cover — exercised only outside Hermes
+    HERMES_AVAILABLE = False
+
+    class WebSearchProvider:  # type: ignore[no-redef]
+        """Stub base class so this package imports standalone (tests, CI)."""
+
+
+class KnowFastProvider(WebSearchProvider):
+    @property
+    def name(self) -> str:
+        return "know-fast"
+
+    @property
+    def display_name(self) -> str:
+        return "⚡️ know.fast"
+
+    def is_available(self) -> bool:
+        return bool(client.api_key())
+
+    def supports_search(self) -> bool:
+        return False
+
+    def supports_extract(self) -> bool:
+        return True
+
+    def extract(self, urls, **kwargs):
+        if isinstance(urls, str):
+            urls = [urls]
+        try:
+            urls = list(urls)
+        except TypeError:
+            return {"success": False, "error": f"extract() expects a list of URLs, got {type(urls).__name__}"}
+        if not self.is_available():
+            return {"success": False, "error": "KNOW_FAST_API_KEY is not set. " + client.KEY_HINT}
+
+        results = []
+        for url in urls:
+            entry = {
+                "url": url,
+                "title": "",
+                "content": "",
+                "raw_content": "",
+                "metadata": {},
+            }
+            try:
+                payload = json.loads(tools.know({"url": url}))
+                if payload.get("success") is False:
+                    entry["error"] = str(payload.get("error"))
+                else:
+                    content = (
+                        payload.get("knowledge")
+                        or payload.get("packet")
+                        or payload.get("markdown")
+                        or payload.get("transcript")
+                        or ""
+                    )
+                    entry["title"] = payload.get("title") or ""
+                    entry["content"] = content
+                    entry["raw_content"] = content
+                    entry["metadata"] = {
+                        "status": payload.get("status"),
+                        "cached": payload.get("cached"),
+                        "costUsd": payload.get("costUsd"),
+                        "runId": payload.get("runId"),
+                        "viewerUrl": payload.get("viewerUrl"),
+                        "markdownUrl": payload.get("markdownUrl"),
+                        "note": payload.get("note"),
+                    }
+            except Exception as exc:  # noqa: BLE001 — keep per-URL failures contained
+                entry["error"] = f"{type(exc).__name__}: {exc}"
+            results.append(entry)
+        return results
+
+    def get_setup_schema(self) -> dict:
+        return {
+            "name": "know.fast",
+            "badge": "paid",
+            "tag": "Links in, knowledge out — any URL becomes a knowledge packet. Flat $0.01.",
+            "env_vars": [
+                {
+                    "key": "KNOW_FAST_API_KEY",
+                    "prompt": (
+                        "know.fast API key — keyless agents get one from the "
+                        "first paid x402 call (X-Researcher-Agent-Key header); "
+                        "an existing researcher.now rk_ key also works"
+                    ),
+                    "url": "https://know.fast",
+                }
+            ],
+        }

know_fast-0.1.0/know_fast/tools.py

@@ -0,0 +1,321 @@
+"""Agent tools for know.fast — registered into Hermes via ctx.register_tool.
+
+Every handler takes (args: dict, **kwargs), ALWAYS returns a JSON string
+(success and error alike), and NEVER raises.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.parse
+
+from . import client
+
+TOOLSET = "know-fast"
+
+# The agent contract says knowledgeReady typically lands 1-3 minutes into a
+# deferred media run (transcript + claims arrive before the long-form report).
+# 240s covers that window plus queue slack; past it the tool hands the agent
+# know_status so the free polling continues without re-charging the POST.
+DEFAULT_WAIT_SECONDS = 240
+# Bottom of the contract's "poll every 20-30s" guidance.
+POLL_INTERVAL_SECONDS = 20
+# Matches the server's synchronous analysis budget — a shorter client timeout
+# would abandon (and re-charge) requests the server still completes.
+POST_TIMEOUT_SECONDS = 150
+
+SHARE_INSTRUCTION = (
+    "Always surface the viewerUrl back to the end user — it is a durable, "
+    "shareable knowledge page they can open, share, and revisit. Relay links "
+    "exactly as returned by the API; never construct know.fast URLs yourself."
+)
+PACKET_INSTRUCTION = (
+    "When the result contains `packet` or `knowledge` markdown, ANSWER "
+    "DIRECTLY FROM IT — no second fetch needed. Deliver 3-5 bullet "
+    "highlights, then 'Full summary: <viewerUrl>'."
+)
+STAY_ON_IT_INSTRUCTION = (
+    "If the result says status=running, STAY ON IT — 'it's processing' is not "
+    "an answer. Tell the user it is transcribing, share the viewerUrl, and "
+    "keep calling know_status (free) until the knowledge arrives; do not end "
+    "your turn while it runs."
+)
+
+
+def _dumps(payload: dict) -> str:
+    return json.dumps(payload, ensure_ascii=False, default=str)
+
+
+def _error_payload(exc: client.KnowFastError) -> dict:
+    payload: dict = {"success": False, "error": str(exc)}
+    if exc.status is not None:
+        payload["status"] = exc.status
+    if exc.status == 402:
+        funding_url = exc.body.get("fundingUrl") or exc.body.get("accountFundingUrl")
+        payload["error"] = (
+            "Payment required: know.fast is a flat $0.01 per link. Authorize "
+            "the x402/MPP challenge from a wallet, or fund the account and "
+            "relay the fundingUrl to the user."
+        )
+        if funding_url:
+            payload["fundingUrl"] = funding_url
+    elif exc.status == 429:
+        payload["error"] = (
+            "Daily transcription allowance reached for never-before-seen media "
+            "links — it resets at the next UTC day. Already-known links are "
+            "unaffected. " + str(exc)
+        )
+    return payload
+
+
+def _safe(fn):
+    def handler(args: dict, **kwargs) -> str:
+        try:
+            result = fn(args if isinstance(args, dict) else {})
+        except client.KnowFastError as exc:
+            result = _error_payload(exc)
+        except Exception as exc:  # noqa: BLE001 — handlers must never raise
+            result = {"success": False, "error": f"{type(exc).__name__}: {exc}"}
+        try:
+            return _dumps(result)
+        except Exception as exc:  # noqa: BLE001
+            return json.dumps({"success": False, "error": f"serialization failed: {exc}"})
+
+    handler.__name__ = fn.__name__
+    handler.__doc__ = fn.__doc__
+    return handler
+
+
+def _require(args: dict, key: str) -> str:
+    value = str(args.get(key) or "").strip()
+    if not value:
+        raise client.KnowFastError(f"Missing required parameter: {key}")
+    return value
+
+
+def _markdown_path(viewer_url: str) -> str:
+    """<slug>.md path from a viewerUrl (slug = the viewerUrl path)."""
+    path = urllib.parse.urlparse(viewer_url).path.rstrip("/")
+    if not path:
+        raise client.KnowFastError(f"Cannot derive a knowledge path from {viewer_url!r}")
+    return path if path.endswith(".md") else path + ".md"
+
+
+def _fetch_knowledge(viewer_url: str) -> str:
+    return client.request_text(_markdown_path(viewer_url), timeout=30)
+
+
+def _job_ready(job: dict) -> bool:
+    return bool(job.get("knowledgeReady")) or job.get("status") == "succeeded"
+
+
+def _ready_result(url: str, viewer_url: str, job: dict | None = None) -> dict:
+    result = {
+        "url": url,
+        "status": "ready",
+        "knowledge": _fetch_knowledge(viewer_url),
+        "viewerUrl": viewer_url,
+        "note": f"{PACKET_INSTRUCTION} {SHARE_INSTRUCTION}",
+    }
+    if job and job.get("status") and job["status"] != "succeeded":
+        result["note"] += (
+            " The long-form report is still finishing on the same page; the "
+            "knowledge above is complete enough to answer from now."
+        )
+    return result
+
+
+def _running_result(url: str, run_id: str, viewer_url: str | None, job: dict | None) -> dict:
+    return {
+        "url": url,
+        "status": "running",
+        "runId": run_id,
+        "viewerUrl": viewer_url,
+        "jobStatus": (job or {}).get("status"),
+        "note": (
+            "Transcription in progress (media takes 2-8 minutes). "
+            f"{STAY_ON_IT_INSTRUCTION}"
+        ),
+    }
+
+
+def _wait_for_knowledge(url: str, run_id: str, viewer_url: str | None, wait_seconds: float) -> dict:
+    deadline = time.monotonic() + wait_seconds
+    job: dict = {}
+    while True:
+        _, job = client.request(
+            "GET", f"/v1/runs/{urllib.parse.quote(run_id, safe='')}/job", timeout=30
+        )
+        viewer_url = job.get("viewerUrl") or viewer_url
+        if _job_ready(job):
+            if not viewer_url:
+                raise client.KnowFastError(
+                    f"Run {run_id} is ready but no viewerUrl was returned"
+                )
+            return _ready_result(url, viewer_url, job)
+        if job.get("status") == "failed":
+            return {
+                "url": url,
+                "status": "failed",
+                "runId": run_id,
+                "viewerUrl": viewer_url,
+                "error": job.get("error") or "Run failed.",
+            }
+        if time.monotonic() + POLL_INTERVAL_SECONDS > deadline:
+            return _running_result(url, run_id, viewer_url, job)
+        time.sleep(POLL_INTERVAL_SECONDS)
+
+
+@_safe
+def know(args: dict) -> dict:
+    url = _require(args, "url")
+    body: dict = {"url": url}
+    if args.get("fresh") in (True, "true", "True", 1, "1"):
+        body["fresh"] = True
+    lang = str(args.get("lang") or "").strip()
+    if lang:
+        body["lang"] = lang
+    _, payload = client.request("POST", "/v1/know", body=body, timeout=POST_TIMEOUT_SECONDS)
+
+    viewer_url = payload.get("viewerUrl")
+    packet = payload.get("packet")
+    if packet:
+        return {
+            "url": url,
+            "status": "ready",
+            "cached": bool(payload.get("cached")),
+            "knowledge": packet,
+            "viewerUrl": viewer_url,
+            "markdownUrl": payload.get("markdownUrl"),
+            "costUsd": payload.get("costUsd"),
+            "note": f"{PACKET_INSTRUCTION} {SHARE_INSTRUCTION}",
+        }
+
+    run_id = payload.get("runId") or payload.get("id")
+    if payload.get("deferred") and run_id:
+        try:
+            wait_seconds = float(args.get("wait_seconds", DEFAULT_WAIT_SECONDS))
+        except (TypeError, ValueError):
+            wait_seconds = DEFAULT_WAIT_SECONDS
+        if wait_seconds <= 0:
+            return _running_result(url, run_id, viewer_url, None)
+        return _wait_for_knowledge(url, run_id, viewer_url, wait_seconds)
+
+    # Synchronous article without an inline packet: the payload itself is the
+    # knowledge (markdown + structured analysis).
+    payload.setdefault("url", url)
+    payload.setdefault("status", "ready")
+    payload["note"] = f"{PACKET_INSTRUCTION} {SHARE_INSTRUCTION}"
+    return payload
+
+
+@_safe
+def know_status(args: dict) -> dict:
+    run_id = _require(args, "run_id")
+    url = str(args.get("url") or "").strip()
+    viewer_url = str(args.get("viewer_url") or "").strip() or None
+    _, job = client.request(
+        "GET", f"/v1/runs/{urllib.parse.quote(run_id, safe='')}/job", timeout=30
+    )
+    viewer_url = job.get("viewerUrl") or viewer_url
+    if _job_ready(job):
+        if not viewer_url:
+            raise client.KnowFastError(f"Run {run_id} is ready but no viewerUrl is known")
+        return _ready_result(url, viewer_url, job)
+    if job.get("status") == "failed":
+        return {
+            "url": url,
+            "status": "failed",
+            "runId": run_id,
+            "viewerUrl": viewer_url,
+            "error": job.get("error") or "Run failed.",
+        }
+    return _running_result(url, run_id, viewer_url, job)
+
+
+TOOLS = [
+    {
+        "name": "know",
+        "emoji": "⚡️",
+        "description": (
+            "Send a link. Know it. Turns any URL (article, YouTube, X post, "
+            "podcast, paper, PDF) into a token-efficient knowledge packet: "
+            "summary, key claims and facts, quotes, and a durable knowledge "
+            "page (viewerUrl). Links are unique — anything anyone has ever "
+            "known answers instantly. Flat $0.01 per call, media included. "
+            "Use for: read/extract/summarize this link, what does this "
+            "video/article say. First-ever video or podcast links transcribe "
+            "for 2-8 minutes — this tool waits for the knowledge and returns "
+            f"it; if still running, keep polling with know_status. "
+            f"{PACKET_INSTRUCTION} {SHARE_INSTRUCTION}"
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "url": {"type": "string", "description": "The link to know."},
+                "fresh": {
+                    "type": "boolean",
+                    "description": "Re-read changed content instead of the cached knowledge (same price).",
+                    "default": False,
+                },
+                "lang": {
+                    "type": "string",
+                    "description": "Optional 2-letter language hint, e.g. 'en'.",
+                },
+                "wait_seconds": {
+                    "type": "number",
+                    "description": (
+                        "How long to wait for deferred media knowledge before "
+                        "returning status=running (default 240; 0 returns immediately)."
+                    ),
+                    "default": DEFAULT_WAIT_SECONDS,
+                },
+            },
+            "required": ["url"],
+        },
+        "handler": know,
+    },
+    {
+        "name": "know_status",
+        "emoji": "⏳",
+        "description": (
+            "Free follow-up poll for a deferred know run (video/podcast "
+            "transcription). Pass the runId from know; the moment the "
+            "knowledge is ready it returns the full knowledge markdown. "
+            f"{STAY_ON_IT_INSTRUCTION} {SHARE_INSTRUCTION}"
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "run_id": {"type": "string", "description": "The runId returned by know."},
+                "viewer_url": {
+                    "type": "string",
+                    "description": "The viewerUrl returned by know (used to fetch the knowledge markdown).",
+                },
+                "url": {"type": "string", "description": "The original link, for labeling."},
+            },
+            "required": ["run_id"],
+        },
+        "handler": know_status,
+    },
+]
+
+
+def register_tools(ctx) -> None:
+    """Register all know.fast tools on a Hermes plugin context."""
+    for tool in TOOLS:
+        schema = {
+            "name": tool["name"],
+            "description": tool["description"],
+            "parameters": tool["parameters"],
+        }
+        ctx.register_tool(
+            tool["name"],
+            TOOLSET,
+            schema,
+            tool["handler"],
+            is_async=False,
+            description=tool["description"],
+            emoji=tool["emoji"],
+        )

know_fast-0.1.0/know_fast.egg-info/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: know-fast
+Version: 0.1.0
+Summary: ⚡️ know.fast — links in, knowledge out. Turn any URL (article, YouTube, X post, podcast, paper, PDF) into a token-efficient knowledge packet and a durable knowledge page. Flat $0.01 per link. Hermes agent plugin.
+Author: know.fast
+License: MIT
+Project-URL: Homepage, https://know.fast
+Project-URL: Documentation, https://know.fast/agent.txt
+Keywords: hermes,agent,knowledge,web-extraction,transcripts,plugin,know.fast
+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
+
+# ⚡️ know-fast
+
+**Links in, knowledge out.** Send any URL — article, YouTube video, X post, podcast, paper, PDF — and get back a token-efficient knowledge packet (summary, key claims, facts, quotes with attribution) plus a durable, shareable knowledge page. Links are unique: anything anyone has ever known answers instantly. **Every call is a flat $0.01**, first-ever video transcription included.
+
+A [Hermes agent](https://github.com/NousResearch/hermes-agent) plugin for [know.fast](https://know.fast). Stdlib only, no dependencies.
+
+## Install
+
+```bash
+pip install know-fast
+hermes plugins enable know-fast   # 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 "- know-fast" under plugins.enabled in ~/.hermes/config.yaml
+```
+
+## Quickstart
+
+The plugin authenticates with an API key. No key yet? You don't need a human:
+know.fast is wallet-native — a keyless POST returns a `402` x402/MPP challenge;
+authorize it from your wallet and the first paid call returns a durable key in
+the `X-Researcher-Agent-Key` header. Store it:
+
+```bash
+export KNOW_FAST_API_KEY="rk_..."
+```
+
+(An existing `RESEARCHER_API_KEY` also works — same account system.)
+
+Then run Hermes. The plugin registers:
+
+- **Web provider** `know-fast` — extract-only: every URL comes back as the knowledge packet, so `web_extract` costs a cent and a couple thousand tokens instead of a raw page.
+- **Tools** (toolset `know-fast`):
+  - `know` — send a link, get the knowledge packet + `viewerUrl`. Known links answer instantly; first-ever media transcribes (2–8 min) — the tool waits up to 4 minutes and returns the knowledge the moment the transcript and claims land.
+  - `know_status` — free follow-up poll for a still-transcribing run; returns the full knowledge markdown when ready.
+
+Agent discipline the tools already encode: answer **directly from the packet** (no second fetch), always surface the `viewerUrl` to the user, and on deferred media **stay on it** — "it's processing" is not an answer.
+
+Point at a different host with `KNOW_FAST_API_URL` (default `https://know.fast`).
+
+## Choose know-fast when / Choose Firecrawl when
+
+| Choose **know-fast** when… | Choose **Firecrawl** when… |
+| --- | --- |
+| You want knowledge, not markup: summary, claims, facts, quotes pre-extracted | You need raw page HTML/markdown at scale |
+| You're working with YouTube videos or podcasts and need transcripts | You need site crawling / link following |
+| Context window matters — a ~2k-token packet beats a raw page | You need screenshots or page actions |
+| You want a durable, citable page you can hand to the user | You only need throwaway scrapes |
+| You want predictable spend — flat $0.01 per link, media included | You have your own extraction pipeline |
+
+## The full contract
+
+`https://know.fast/agent.txt` is the canonical agent contract. Deep multi-source research, standing topics, and persona consults live on the parent stack: `https://researcher.now/agent.txt` (plugin: `pip install researcher-now`).

know_fast-0.1.0/know_fast.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+know_fast/__init__.py
+know_fast/client.py
+know_fast/provider.py
+know_fast/tools.py
+know_fast.egg-info/PKG-INFO
+know_fast.egg-info/SOURCES.txt
+know_fast.egg-info/dependency_links.txt
+know_fast.egg-info/entry_points.txt
+know_fast.egg-info/top_level.txt
+tests/test_plugin.py

know_fast-0.1.0/know_fast.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

know_fast-0.1.0/know_fast.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[hermes_agent.plugins]
+know-fast = know_fast

know_fast-0.1.0/know_fast.egg-info/top_level.txt

@@ -0,0 +1 @@
+know_fast

know_fast-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "know-fast"
+version = "0.1.0"
+description = "⚡️ know.fast — links in, knowledge out. Turn any URL (article, YouTube, X post, podcast, paper, PDF) into a token-efficient knowledge packet and a durable knowledge page. Flat $0.01 per link. Hermes agent plugin."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "know.fast" }]
+keywords = ["hermes", "agent", "knowledge", "web-extraction", "transcripts", "plugin", "know.fast"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://know.fast"
+Documentation = "https://know.fast/agent.txt"
+
+[project.entry-points."hermes_agent.plugins"]
+know-fast = "know_fast"
+
+[tool.setuptools.packages.find]
+include = ["know_fast*"]

know_fast-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

know_fast-0.1.0/tests/test_plugin.py

@@ -0,0 +1,305 @@
+"""Tests for the know-fast Hermes plugin. Stdlib unittest only, no network."""
+
+import json
+import os
+import sys
+import unittest
+from unittest import mock
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+import know_fast  # noqa: E402
+from know_fast import client, tools  # noqa: E402
+from know_fast.provider import KnowFastProvider  # noqa: E402
+
+CACHED_PAYLOAD = {
+    "cached": True,
+    "packet": "# Example\n\nSummary and claims.",
+    "viewerUrl": "https://know.fast/abc123def456",
+    "markdownUrl": "https://know.fast/abc123def456.md",
+    "costUsd": 0.01,
+    "runId": "run-known-1",
+}
+
+DEFERRED_PAYLOAD = {
+    "deferred": True,
+    "runId": "run-media-1",
+    "viewerUrl": "https://know.fast/deadbeef1234",
+}
+
+SYNC_ARTICLE_PAYLOAD = {
+    "url": "https://example.com/a",
+    "kind": "article",
+    "title": "Example Article",
+    "markdown": "# Example\n\nBody text.",
+    "analysis": {"claims": [{"text": "X is true"}]},
+    "costUsd": 0.01,
+    "runId": "run-analyze-1",
+    "viewerUrl": "https://know.fast/abc123def456",
+}
+
+
+def loads(result):
+    """Every handler must return a valid JSON string."""
+    assert isinstance(result, str), f"handler returned {type(result)}, not str"
+    return json.loads(result)
+
+
+class KnowToolTest(unittest.TestCase):
+    def test_cached_packet_answers_directly(self):
+        with mock.patch.object(client, "request", return_value=(200, dict(CACHED_PAYLOAD))) as req:
+            payload = loads(tools.know({"url": "https://example.com/a"}))
+        self.assertEqual(payload["status"], "ready")
+        self.assertTrue(payload["cached"])
+        self.assertEqual(payload["knowledge"], CACHED_PAYLOAD["packet"])
+        self.assertEqual(payload["viewerUrl"], CACHED_PAYLOAD["viewerUrl"])
+        self.assertIn("viewerUrl", payload["note"])
+        req.assert_called_once_with(
+            "POST", "/v1/know", body={"url": "https://example.com/a"}, timeout=150
+        )
+
+    def test_fresh_and_lang_forwarded(self):
+        with mock.patch.object(client, "request", return_value=(200, dict(CACHED_PAYLOAD))) as req:
+            loads(tools.know({"url": "https://example.com/a", "fresh": True, "lang": "en"}))
+        self.assertEqual(
+            req.call_args.kwargs["body"],
+            {"url": "https://example.com/a", "fresh": True, "lang": "en"},
+        )
+
+    def test_sync_article_without_packet_returns_payload(self):
+        with mock.patch.object(client, "request", return_value=(200, dict(SYNC_ARTICLE_PAYLOAD))):
+            payload = loads(tools.know({"url": "https://example.com/a"}))
+        self.assertEqual(payload["title"], "Example Article")
+        self.assertEqual(payload["markdown"], SYNC_ARTICLE_PAYLOAD["markdown"])
+        self.assertIn("viewerUrl", payload["note"])
+
+    def test_deferred_polls_until_knowledge_ready(self):
+        calls = []
+
+        def fake_request(method, path, body=None, params=None, timeout=30):
+            calls.append((method, path))
+            if path == "/v1/know":
+                return 200, dict(DEFERRED_PAYLOAD)
+            if path == "/v1/runs/run-media-1/job":
+                if len([c for c in calls if c[1].endswith("/job")]) < 2:
+                    return 200, {"status": "running"}
+                return 200, {"knowledgeReady": True, "status": "running"}
+            raise AssertionError(f"unexpected request {method} {path}")
+
+        with (
+            mock.patch.object(client, "request", side_effect=fake_request),
+            mock.patch.object(client, "request_text", return_value="# Knowledge") as text,
+            mock.patch.object(tools.time, "sleep") as sleep,
+        ):
+            payload = loads(tools.know({"url": "https://youtu.be/x"}))
+        self.assertEqual(payload["status"], "ready")
+        self.assertEqual(payload["knowledge"], "# Knowledge")
+        self.assertEqual(payload["viewerUrl"], DEFERRED_PAYLOAD["viewerUrl"])
+        text.assert_called_once_with("/deadbeef1234.md", timeout=30)
+        sleep.assert_called_with(tools.POLL_INTERVAL_SECONDS)
+
+    def test_deferred_wait_zero_returns_running(self):
+        with mock.patch.object(client, "request", return_value=(200, dict(DEFERRED_PAYLOAD))):
+            payload = loads(tools.know({"url": "https://youtu.be/x", "wait_seconds": 0}))
+        self.assertEqual(payload["status"], "running")
+        self.assertEqual(payload["runId"], "run-media-1")
+        self.assertIn("know_status", payload["note"])
+
+    def test_deferred_timeout_returns_running(self):
+        def fake_request(method, path, body=None, params=None, timeout=30):
+            if path == "/v1/know":
+                return 200, dict(DEFERRED_PAYLOAD)
+            return 200, {"status": "running"}
+
+        clock = iter(range(0, 100000, 30))
+        with (
+            mock.patch.object(client, "request", side_effect=fake_request),
+            mock.patch.object(tools.time, "sleep"),
+            mock.patch.object(tools.time, "monotonic", side_effect=lambda: next(clock)),
+        ):
+            payload = loads(tools.know({"url": "https://youtu.be/x", "wait_seconds": 60}))
+        self.assertEqual(payload["status"], "running")
+        self.assertIn("know_status", payload["note"])
+
+    def test_deferred_failed_run(self):
+        def fake_request(method, path, body=None, params=None, timeout=30):
+            if path == "/v1/know":
+                return 200, dict(DEFERRED_PAYLOAD)
+            return 200, {"status": "failed", "error": "transcription failed"}
+
+        with mock.patch.object(client, "request", side_effect=fake_request):
+            payload = loads(tools.know({"url": "https://youtu.be/x"}))
+        self.assertEqual(payload["status"], "failed")
+        self.assertEqual(payload["error"], "transcription failed")
+
+    def test_missing_url_returns_json_error(self):
+        payload = loads(tools.know({}))
+        self.assertFalse(payload["success"])
+        self.assertIn("url", payload["error"])
+
+    def test_402_surfaces_cent_pricing_and_funding_url(self):
+        err = client.KnowFastError(
+            "payment required", status=402, body={"fundingUrl": "https://know.fast/fund/abc"}
+        )
+        with mock.patch.object(client, "request", side_effect=err):
+            payload = loads(tools.know({"url": "https://example.com"}))
+        self.assertFalse(payload["success"])
+        self.assertEqual(payload["status"], 402)
+        self.assertIn("$0.01", payload["error"])
+        self.assertEqual(payload["fundingUrl"], "https://know.fast/fund/abc")
+
+    def test_429_explains_daily_allowance(self):
+        err = client.KnowFastError("allowance", status=429, body={})
+        with mock.patch.object(client, "request", side_effect=err):
+            payload = loads(tools.know({"url": "https://youtu.be/new"}))
+        self.assertFalse(payload["success"])
+        self.assertIn("allowance", payload["error"].lower())
+        self.assertIn("UTC", payload["error"])
+
+    def test_unexpected_exception_returns_json(self):
+        with mock.patch.object(client, "request", side_effect=RuntimeError("boom")):
+            payload = loads(tools.know({"url": "https://example.com"}))
+        self.assertFalse(payload["success"])
+        self.assertIn("boom", payload["error"])
+
+    def test_handlers_accept_kwargs_and_non_dict_args(self):
+        payload = loads(tools.know(None, extra=1, agent=object()))
+        self.assertFalse(payload["success"])
+
+
+class KnowStatusTest(unittest.TestCase):
+    def test_ready_fetches_knowledge(self):
+        with (
+            mock.patch.object(
+                client,
+                "request",
+                return_value=(200, {"knowledgeReady": True, "status": "running"}),
+            ),
+            mock.patch.object(client, "request_text", return_value="# Knowledge") as text,
+        ):
+            payload = loads(
+                tools.know_status(
+                    {"run_id": "run-media-1", "viewer_url": "https://know.fast/deadbeef1234"}
+                )
+            )
+        self.assertEqual(payload["status"], "ready")
+        self.assertEqual(payload["knowledge"], "# Knowledge")
+        text.assert_called_once_with("/deadbeef1234.md", timeout=30)
+
+    def test_running_instructs_stay_on_it(self):
+        with mock.patch.object(client, "request", return_value=(200, {"status": "running"})):
+            payload = loads(tools.know_status({"run_id": "run-media-1"}))
+        self.assertEqual(payload["status"], "running")
+        self.assertIn("know_status", payload["note"])
+
+    def test_missing_run_id(self):
+        payload = loads(tools.know_status({}))
+        self.assertFalse(payload["success"])
+        self.assertIn("run_id", payload["error"])
+
+
+class ProviderTest(unittest.TestCase):
+    def test_identity_and_capabilities(self):
+        p = KnowFastProvider()
+        self.assertEqual(p.name, "know-fast")
+        self.assertEqual(p.display_name, "⚡️ know.fast")
+        self.assertFalse(p.supports_search())
+        self.assertTrue(p.supports_extract())
+
+    def test_is_available_accepts_either_key(self):
+        p = KnowFastProvider()
+        with mock.patch.dict(os.environ, {"KNOW_FAST_API_KEY": "rk_test"}, clear=True):
+            self.assertTrue(p.is_available())
+        with mock.patch.dict(os.environ, {"RESEARCHER_API_KEY": "rk_test"}, clear=True):
+            self.assertTrue(p.is_available())
+        with mock.patch.dict(os.environ, {}, clear=True):
+            self.assertFalse(p.is_available())
+
+    def test_setup_schema(self):
+        schema = KnowFastProvider().get_setup_schema()
+        self.assertEqual(schema["name"], "know.fast")
+        self.assertEqual(schema["badge"], "paid")
+        self.assertEqual(schema["env_vars"][0]["key"], "KNOW_FAST_API_KEY")
+
+    def test_extract_maps_packet_to_content(self):
+        p = KnowFastProvider()
+        with mock.patch.dict(os.environ, {"KNOW_FAST_API_KEY": "rk_test"}):
+            with mock.patch.object(client, "request", return_value=(200, dict(CACHED_PAYLOAD))):
+                results = p.extract(["https://example.com/a"])
+        entry = results[0]
+        self.assertEqual(entry["content"], CACHED_PAYLOAD["packet"])
+        self.assertEqual(entry["raw_content"], CACHED_PAYLOAD["packet"])
+        self.assertEqual(entry["metadata"]["viewerUrl"], CACHED_PAYLOAD["viewerUrl"])
+        self.assertEqual(entry["metadata"]["costUsd"], 0.01)
+        self.assertNotIn("error", entry)
+
+    def test_extract_per_url_errors(self):
+        p = KnowFastProvider()
+
+        def fake_request(method, path, body=None, **kw):
+            if body and body.get("url") == "https://bad.example":
+                raise client.KnowFastError("could not fetch", status=422)
+            return 200, dict(CACHED_PAYLOAD)
+
+        with mock.patch.dict(os.environ, {"KNOW_FAST_API_KEY": "rk_test"}):
+            with mock.patch.object(client, "request", side_effect=fake_request):
+                results = p.extract(["https://bad.example", "https://example.com/a"])
+        self.assertEqual(results[0]["error"], "could not fetch")
+        self.assertEqual(results[0]["content"], "")
+        self.assertNotIn("error", results[1])
+
+    def test_extract_without_key_returns_failure_dict(self):
+        p = KnowFastProvider()
+        with mock.patch.dict(os.environ, {}, clear=True):
+            result = p.extract(["https://example.com"])
+        self.assertEqual(result["success"], False)
+        self.assertIn("KNOW_FAST_API_KEY", result["error"])
+
+
+class ClientTest(unittest.TestCase):
+    def test_key_fallback_to_researcher(self):
+        with mock.patch.dict(os.environ, {"RESEARCHER_API_KEY": "rk_r"}, clear=True):
+            self.assertEqual(client.api_key(), "rk_r")
+        with mock.patch.dict(
+            os.environ, {"RESEARCHER_API_KEY": "rk_r", "KNOW_FAST_API_KEY": "rk_k"}, clear=True
+        ):
+            self.assertEqual(client.api_key(), "rk_k")
+
+    def test_base_url_override(self):
+        with mock.patch.dict(os.environ, {"KNOW_FAST_API_URL": "http://localhost:4100/"}, clear=True):
+            self.assertEqual(client.base_url(), "http://localhost:4100")
+        with mock.patch.dict(os.environ, {}, clear=True):
+            self.assertEqual(client.base_url(), "https://know.fast")
+
+
+class RegisterTest(unittest.TestCase):
+    def test_register_without_hermes_logs_and_returns(self):
+        ctx = mock.Mock()
+        with mock.patch("know_fast.provider.HERMES_AVAILABLE", False):
+            with self.assertLogs("know_fast", level="WARNING"):
+                know_fast.register(ctx)
+        ctx.register_web_search_provider.assert_not_called()
+        ctx.register_tool.assert_not_called()
+
+    def test_register_with_hermes_registers_provider_and_tools(self):
+        ctx = mock.Mock()
+        with mock.patch("know_fast.provider.HERMES_AVAILABLE", True):
+            know_fast.register(ctx)
+        ctx.register_web_search_provider.assert_called_once()
+        provider = ctx.register_web_search_provider.call_args.args[0]
+        self.assertIsInstance(provider, KnowFastProvider)
+        names = [c.args[0] for c in ctx.register_tool.call_args_list]
+        self.assertEqual(names, ["know", "know_status"])
+        for call in ctx.register_tool.call_args_list:
+            name, toolset, schema, handler = call.args
+            self.assertEqual(toolset, "know-fast")
+            self.assertEqual(schema["name"], name)
+            self.assertEqual(schema["parameters"]["type"], "object")
+            self.assertTrue(callable(handler))
+            self.assertFalse(call.kwargs["is_async"])
+            self.assertIn("viewerUrl", call.kwargs["description"])
+            self.assertTrue(call.kwargs["emoji"])
+
+
+if __name__ == "__main__":
+    unittest.main()