know-fast 0.1.0__py3-none-any.whl

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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+know_fast/__init__.py,sha256=rl0WwCbKKROmQd6l57mXOf3XwHRBmFBEqWvm0KsrBuM,1089
+know_fast/client.py,sha256=lerLg76OO5QkhsaowZ4Y31VNY0ZEGoiT5JUk-SvjQAo,5789
+know_fast/provider.py,sha256=rB1YMIngwTFKvUy0jtB6tCmfL6AZONBb7noAufrZ2kw,3813
+know_fast/tools.py,sha256=DPu89XR9aOpGqsAWAAqlV5s-BTf7kW05epZzgIVqd2o,11946
+know_fast-0.1.0.dist-info/METADATA,sha256=I7HpZ0kflwe3M_PQj-Ded_ScJtSq2vhv9aJ6YEy6zHk,3966
+know_fast-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+know_fast-0.1.0.dist-info/entry_points.txt,sha256=aIJVa2w1faLMTLhT849sTWUcBGlKbwHZh5Zt4p1Er_8,45
+know_fast-0.1.0.dist-info/top_level.txt,sha256=039Duxpe9DVHLz6Xfc0_AE0IuuhCLd0nNunD1lOgEBI,10
+know_fast-0.1.0.dist-info/RECORD,,

know_fast-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

know_fast-0.1.0.dist-info/entry_points.txt

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

know_fast-0.1.0.dist-info/top_level.txt

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