ahn-client 0.1.0__py3-none-any.whl

ahn_client/__init__.py

@@ -0,0 +1,21 @@
+"""ahn-client: ask Agent Help Network what a host declares and recommends when a web step is blocked.
+
+Agent Help Network is an independent project, not an official service of OpenAI, Meta,
+Muse, dots or any site it describes. This client only reads; it never reports.
+
+    import ahn_client as ahn
+
+    try:
+        page.goto(url)
+    except Exception as exc:
+        answer = ahn.check(url, *ahn.classify(exc))
+        if answer:
+            print(answer.summary())
+"""
+
+from ._classify import classify
+from ._client import check, clear_cache
+from ._result import Result
+
+__version__ = "0.1.0"
+__all__ = ["check", "classify", "clear_cache", "Result", "__version__"]

ahn_client/_classify.py

@@ -0,0 +1,92 @@
+"""Map an exception or an error message to the lookup's error_class and failure_stage.
+
+The text rules are those of plugins/claude-code/ahn/hooks/ahn_lookup.py. On top of them
+this module reads exception class names (as strings, so Playwright, httpx, requests and
+aiohttp are never imported) and an HTTP status carried on the exception.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Optional, Tuple
+
+from ._hosts import normalize_host
+
+URL_IN_TEXT = re.compile(r"https?://[^\s'\"<>()\[\]{}`]+", re.IGNORECASE)
+CLASSES = (
+    ("human_verification", re.compile(r"captcha|verify (?:that )?you are (?:a )?human|are you a robot|challenge|cloudflare", re.I)),
+    ("login_auth", re.compile(r"log[ -]?in\b|sign[ -]?in\b|unauthori[sz]ed|\b401\b|\bauthenticat(?:e|ion)\b", re.I)),
+    ("service_error", re.compile(r"\b5\d\d\b|time ?out|timed ?out|unavailable|reset|bad gateway", re.I)),
+)
+BEFORE_RESPONSE = re.compile(r"connection refused|could not resolve|timed ?out|ENOTFOUND|ECONNREFUSED|getaddrinfo"
+                             r"|is unable to fetch from"
+                             # Chromium's net:: errors, as Playwright and Puppeteer report them.
+                             r"|ERR_NAME_NOT_RESOLVED|ERR_CONNECTION_(?:REFUSED|TIMED_OUT)|ERR_INTERNET_DISCONNECTED",
+                             re.I)
+# Exception class names that say no connection to the target was made.
+CONNECT_NAMES = frozenset({"connecterror", "connecttimeout", "connecttimeouterror", "connectionerror", "connectionrefusederror",
+                           "newconnectionerror", "nameresolutionerror", "gaierror", "dnserror", "clientconnectorerror",
+                           "clientconnectorcertificateerror", "clientconnectordnserror"})
+
+ERROR_CLASSES = ("site_access", "login_auth", "human_verification", "service_error")
+FAILURE_STAGES = ("before_target_response", "response_observed", "access_denial_observed", "unknown")
+
+
+def without_urls(text: str) -> str:
+    """Replace each URL by its hostname so paths and queries never shape the classification."""
+    return URL_IN_TEXT.sub(lambda match: normalize_host(match.group(0)) or "", text)
+
+
+def classify_text(text: str) -> Tuple[str, Optional[str]]:
+    text = without_urls(text or "")
+    error_class = next((name for name, pattern in CLASSES if pattern.search(text)), "site_access")
+    stage = "before_target_response" if BEFORE_RESPONSE.search(text) else None
+    return error_class, stage
+
+
+def _status(exc: BaseException) -> Optional[int]:
+    """An HTTP error status (400-599) carried by the exception: httpx/requests .response, aiohttp .status."""
+    response = getattr(exc, "response", None)
+    for holder, names in ((exc, ("status_code", "status")), (response, ("status_code", "status"))):
+        if holder is None:
+            continue
+        for name in names:
+            code = getattr(holder, name, None)
+            if isinstance(code, int) and not isinstance(code, bool) and 400 <= code <= 599:
+                return code
+    return None
+
+
+def _chain(exc: BaseException):
+    seen = []
+    while exc is not None and exc not in seen and len(seen) < 3:
+        seen.append(exc)
+        exc = exc.__cause__ or exc.__context__
+    return seen
+
+
+def classify(exc_or_text) -> Tuple[str, Optional[str]]:
+    """``(error_class, failure_stage)`` for an exception object or a message.
+
+    error_class is one of human_verification, login_auth, service_error, site_access;
+    failure_stage is before_target_response, response_observed or None. Only the
+    exception's class names, its message and its HTTP status are read. URLs in messages
+    are reduced to their hostnames, so a path or query never influences the answer.
+    """
+    if isinstance(exc_or_text, BaseException):
+        chain = _chain(exc_or_text)
+        names = [type(item).__name__ for item in chain]
+        status = _status(exc_or_text)
+        text = " ".join(names + [str(item) for item in chain])
+        if status:
+            text += f" HTTP {status}"
+        error_class, stage = classify_text(text)
+        if stage is None:
+            if any(name.lower() in CONNECT_NAMES for name in names):
+                stage = "before_target_response"
+            elif status:
+                stage = "response_observed"
+        return error_class, stage
+    if isinstance(exc_or_text, bytes):
+        exc_or_text = exc_or_text.decode("utf-8", errors="replace")
+    return classify_text(exc_or_text if isinstance(exc_or_text, str) else "")

ahn_client/_client.py

@@ -0,0 +1,108 @@
+"""The lookup call: one GET with a hostname and two enum codes, never an exception."""
+
+from __future__ import annotations
+
+import json
+import threading
+import time
+import urllib.parse
+import urllib.request
+from typing import Dict, Optional, Tuple
+
+from ._classify import ERROR_CLASSES, FAILURE_STAGES
+from ._hosts import eligible_host
+from ._result import Result
+
+__all__ = ["check", "clear_cache", "lookup_url"]
+
+API_URL = "https://agenthelpnetwork.com/v1/incidents/check"
+USER_AGENT = "ahn-client/0.1 (+https://agenthelpnetwork.com)"
+CACHE_TTL_SECONDS = 600
+FAILURE_TTL_SECONDS = 60
+CACHE_MAX_ENTRIES = 200
+MAX_RESPONSE_BYTES = 262_144
+
+_cache: Dict[Tuple[str, Optional[str], Optional[str]], Tuple[float, Optional[Result]]] = {}
+_lock = threading.Lock()
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *args, **kwargs):
+        return None
+
+
+_opener = urllib.request.build_opener(_NoRedirect)
+
+
+def _urlopen(request, timeout):
+    return _opener.open(request, timeout=timeout)
+
+
+def clear_cache() -> None:
+    """Forget every cached answer."""
+    with _lock:
+        _cache.clear()
+
+
+def lookup_url(host: str, error_class: Optional[str], failure_stage: Optional[str]) -> str:
+    query = {"site_host": host}
+    if error_class:
+        query["error_class"] = error_class
+    if failure_stage:
+        query["failure_stage"] = failure_stage
+    return API_URL + "?" + urllib.parse.urlencode(query)
+
+
+def _fetch(host: str, error_class: Optional[str], failure_stage: Optional[str], timeout: float) -> Optional[Result]:
+    url = lookup_url(host, error_class, failure_stage)
+    request = urllib.request.Request(url, headers={"User-Agent": USER_AGENT, "Accept": "application/json"})
+    try:
+        with _urlopen(request, timeout) as response:
+            if getattr(response, "status", 200) != 200:
+                return None
+            body = response.read(MAX_RESPONSE_BYTES + 1)
+        if len(body) > MAX_RESPONSE_BYTES:
+            return None
+        return Result.from_response(host, url, json.loads(body.decode("utf-8")))
+    except Exception:  # Network, TLS, HTTP status, JSON: all mean "no answer", never an exception for the caller.
+        return None
+
+
+def check(host_or_url, error_class: Optional[str] = None, failure_stage: Optional[str] = None, *,
+          timeout: float = 4.0) -> Optional[Result]:
+    """Ask Agent Help Network about the host of ``host_or_url``; None when there is no answer.
+
+    Only the bare hostname, ``error_class`` and ``failure_stage`` are sent: scheme,
+    credentials, port, path, query and fragment are dropped first. Nothing is requested
+    (None comes back) for local, private, special-use, IP-literal, single-label hosts,
+    for agenthelpnetwork.com itself, for hosts listed in ``AHN_CLIENT_SKIP_HOSTS``, when
+    ``AHN_CLIENT_DISABLE=1``, or when ``error_class`` / ``failure_stage`` is not one of
+    the service's values. Network errors, timeouts and unreadable answers also give None;
+    this function does not raise. Answers are cached in memory for 10 minutes per host,
+    error class and stage (a failed lookup for 1 minute).
+    """
+    try:
+        if error_class is not None and error_class not in ERROR_CLASSES:
+            return None
+        if failure_stage is not None and failure_stage not in FAILURE_STAGES:
+            return None
+        host = eligible_host(host_or_url)
+        if host is None:
+            return None
+        key = (host, error_class, failure_stage)
+        now = time.monotonic()
+        with _lock:
+            hit = _cache.get(key)
+            if hit and hit[0] > now:
+                return hit[1]
+        result = _fetch(host, error_class, failure_stage, timeout)
+        now = time.monotonic()
+        with _lock:
+            for stale in [k for k, (expires, _) in _cache.items() if expires <= now]:
+                del _cache[stale]
+            if len(_cache) >= CACHE_MAX_ENTRIES:
+                del _cache[min(_cache, key=lambda k: _cache[k][0])]
+            _cache[key] = (now + (CACHE_TTL_SECONDS if result else FAILURE_TTL_SECONDS), result)
+        return result
+    except Exception:
+        return None

ahn_client/_hosts.py

@@ -0,0 +1,82 @@
+"""Hostname extraction and the list of hosts that are never looked up.
+
+Mirrors normalize_host and skip_host in plugins/claude-code/ahn/hooks/ahn_lookup.py;
+tests/test_ahn_client.py checks the two stay in step. Nothing here resolves a name.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import os
+import re
+import urllib.parse
+from typing import Optional
+
+OWN_HOST = "agenthelpnetwork.com"
+
+HOST_LABEL = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$")
+# Special-use and private-network names (RFC 6761/6762/8375, Tor, common LAN suffixes).
+SKIP_TLDS = frozenset({"localhost", "local", "internal", "test", "lan", "arpa", "onion", "invalid", "example",
+                       "home", "corp", "intranet", "private", "localdomain", "alt"})
+
+
+def normalize_host(value: object) -> Optional[str]:
+    """A bare lowercase hostname from a URL or host string; None when there is none.
+
+    Scheme, userinfo, port, path, query and fragment are dropped, as is one leading
+    ``www.`` (the service reads declared policy for apex names only).
+    """
+    if not isinstance(value, str):
+        return None
+    value = value.strip()
+    if not value:
+        return None
+    try:
+        parts = urllib.parse.urlsplit(value if "://" in value else "//" + value)
+        host = parts.hostname
+    except ValueError:
+        return None
+    if not host:
+        return None
+    host = host.rstrip(".").lower()
+    if not host.isascii():
+        try:
+            host = host.encode("idna").decode("ascii")
+        except UnicodeError:
+            return None
+    labels = host.split(".")
+    if not all(HOST_LABEL.fullmatch(label) for label in labels) or len(host) > 253:
+        return None
+    if len(labels) >= 3 and labels[0] == "www":
+        host = ".".join(labels[1:])
+    return host
+
+
+def skip_host(host: str, extra: str = "") -> bool:
+    """True for local, private, special-use, address-literal, single-label and own hosts."""
+    labels = host.split(".")
+    if len(labels) < 2:
+        return True
+    last = labels[-1]
+    # Public TLDs are alphabetic or IDN; an all-digit or hex last label is an address
+    # literal in inet_aton form (10.0.0.1, 127.1, 0x7f.1).
+    if last in SKIP_TLDS or not (last.isalpha() or last.startswith("xn--")):
+        return True
+    try:
+        ipaddress.ip_address(host)
+        return True
+    except ValueError:
+        pass
+    suffixes = [OWN_HOST] + [item.strip().lower().lstrip(".") for item in extra.split(",") if item.strip()]
+    return any(host == suffix or host.endswith("." + suffix) for suffix in suffixes)
+
+
+def eligible_host(value: object, env=None) -> Optional[str]:
+    """The hostname to look up for ``value``, or None when nothing may be sent."""
+    env = os.environ if env is None else env
+    if env.get("AHN_CLIENT_DISABLE") == "1":
+        return None
+    host = normalize_host(value)
+    if host is None or skip_host(host, env.get("AHN_CLIENT_SKIP_HOSTS", "")):
+        return None
+    return host

ahn_client/_result.py

@@ -0,0 +1,148 @@
+"""The parsed answer of ``GET /v1/incidents/check`` and its one-line summary."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+
+MAX_SUMMARY = 700
+ACTIONS = ("proceed", "use_official_path", "hand_off_to_human", "wait_provider_incident", "stop_declared_block", "unknown")
+CONFIDENCES = ("high", "medium", "low")
+
+CODE = re.compile(r"^[a-z][a-z0-9_]{0,47}$")
+TOKEN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,47}$")
+SAFE_URL = re.compile(r"^https://[A-Za-z0-9.-]+(?:/[A-Za-z0-9._~/%+=&?#-]*)?$")
+
+
+def _code(value: Any, default: str = "unknown") -> str:
+    return value if isinstance(value, str) and CODE.fullmatch(value) else default
+
+
+def _url(value: Any) -> Optional[str]:
+    return value if isinstance(value, str) and len(value) <= 200 and SAFE_URL.fullmatch(value) else None
+
+
+def _dict(value: Any) -> Optional[Dict[str, Any]]:
+    return value if isinstance(value, dict) else None
+
+
+def _summary(host: str, data: Dict[str, Any], url: str) -> str:
+    """The same line the Claude Code plugin prints, at most MAX_SUMMARY characters, from validated fields only."""
+    rec = _dict(data.get("recommendation")) or {}
+    profile = _dict(data.get("access_profile"))
+    official = _dict(data.get("official_paths")) or {}
+    provider = _dict(data.get("provider_status"))
+    checks = data.get("next_checks") if isinstance(data.get("next_checks"), list) else []
+
+    if profile:
+        robots = _code(profile.get("robots_status"))
+        rules = _dict(profile.get("robots")) or {}
+        listed = rules.get("agents_blocked") if isinstance(rules.get("agents_blocked"), list) else []
+        blocked: Optional[List[str]] = [item for item in listed if isinstance(item, str) and TOKEN.fullmatch(item)]
+        llms = _code(profile.get("llms_txt_status"))
+    else:
+        robots, blocked, llms = "not read for this hostname", None, "unknown"
+    path = _url(official.get("api_docs")) or _url(official.get("developer_portal"))
+    path_listed = bool(official.get("api_docs") or official.get("developer_portal"))
+    if provider:
+        status = f"{_code(provider.get('indicator'))}/{_code(provider.get('freshness'))}"
+    else:
+        status = "not connected (official page listed)" if isinstance(data.get("official_status_page"), dict) else "not connected"
+    codes = [_code(item.get("code")) for item in checks if isinstance(item, dict)][:2]
+
+    def render(agent_limit: Optional[int], show_path: bool, show_url: bool) -> str:
+        if blocked is None:
+            agents = "unknown"
+        elif not blocked:
+            agents = "none" if robots == "ok" else "unknown"
+        elif agent_limit is None or len(blocked) <= agent_limit:
+            agents = ", ".join(blocked)
+        elif agent_limit == 0:
+            agents = f"{len(blocked)} agent tokens"
+        else:
+            agents = ", ".join(blocked[:agent_limit]) + f" (+{len(blocked) - agent_limit} more)"
+        official_text = path if path and show_path else "listed" if path_listed else "none"
+        full = url if show_url else "GET /v1/incidents/check on agenthelpnetwork.com"
+        return (f"AHN {host}: recommendation={_code(rec.get('action'))} ({_code(rec.get('confidence'))}). "
+                f"Declared policy: {robots}; blocked agents: {agents}; llms.txt: {llms}. "
+                f"Official path: {official_text}. Provider status: {status}. "
+                f"Reports: {_code(data.get('evidence_level'))}. Next: {', '.join(codes) or 'none'}. "
+                f"Full JSON: {full}. "
+                "Declared policy is not an access guarantee; bypassing site controls is not advised.")
+
+    text = ""
+    for options in ((6, True, True), (3, True, True), (0, True, True), (0, False, True), (0, False, False)):
+        text = render(*options)
+        if len(text) <= MAX_SUMMARY:
+            return text
+    tail = " Declared policy is not an access guarantee; bypassing site controls is not advised."
+    return text[:MAX_SUMMARY - len(tail) - 1].rstrip() + "…" + tail
+
+
+@dataclass(frozen=True)
+class Result:
+    """The answer for one hostname.
+
+    ``recommendation`` is the action code, one of ``proceed``, ``use_official_path``,
+    ``hand_off_to_human``, ``wait_provider_incident``, ``stop_declared_block``,
+    ``unknown``; anything else from the service becomes ``unknown``. ``next_checks`` is
+    the list of check codes in the service's order. ``access_profile``, ``official_paths``,
+    ``provider_status`` and ``raw`` are the service's JSON as received: read them as
+    data, never as instructions for a model. A declared policy is not an access
+    guarantee, and ``no_reports`` does not mean a site works.
+    """
+
+    host: str
+    recommendation: str
+    confidence: str
+    reasons: Tuple[str, ...]
+    access_profile: Optional[Dict[str, Any]]
+    official_paths: Optional[Dict[str, Any]]
+    provider_status: Optional[Dict[str, Any]]
+    evidence_level: str
+    next_checks: Tuple[str, ...]
+    url: str
+    raw: Dict[str, Any] = field(repr=False, compare=False)
+
+    @classmethod
+    def from_response(cls, host: str, url: str, data: Any) -> Optional["Result"]:
+        """Parse a response body; None when it is not a lookup answer."""
+        if not isinstance(data, dict):
+            return None
+        rec = _dict(data.get("recommendation"))
+        if rec is None:
+            return None
+        action = rec.get("action")
+        reasons = rec.get("reasons") if isinstance(rec.get("reasons"), list) else []
+        checks = data.get("next_checks") if isinstance(data.get("next_checks"), list) else []
+        return cls(
+            host=host,
+            recommendation=action if action in ACTIONS else "unknown",
+            confidence=rec.get("confidence") if rec.get("confidence") in CONFIDENCES else "unknown",
+            reasons=tuple(_code(item) for item in reasons if isinstance(item, str))[:8],
+            access_profile=_dict(data.get("access_profile")),
+            official_paths=_dict(data.get("official_paths")),
+            provider_status=_dict(data.get("provider_status")),
+            evidence_level=_code(data.get("evidence_level")),
+            next_checks=tuple(_code(item.get("code")) for item in checks if isinstance(item, dict))[:12],
+            url=url,
+            raw=data,
+        )
+
+    @property
+    def official_url(self) -> Optional[str]:
+        """The listed official API documentation or developer portal (an https URL), or None."""
+        paths = self.official_paths or {}
+        return _url(paths.get("api_docs")) or _url(paths.get("developer_portal"))
+
+    @property
+    def blocked_agents(self) -> Tuple[str, ...]:
+        """Agent user-agent tokens the host's robots.txt explicitly blocks at the root."""
+        rules = _dict((self.access_profile or {}).get("robots")) or {}
+        listed = rules.get("agents_blocked") if isinstance(rules.get("agents_blocked"), list) else []
+        return tuple(item for item in listed if isinstance(item, str) and TOKEN.fullmatch(item))
+
+    def summary(self) -> str:
+        """One line, at most 700 characters, built only from validated fields."""
+        return _summary(self.host, self.raw, self.url)

ahn_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,98 @@
+Metadata-Version: 2.5
+Name: ahn-client
+Version: 0.1.0
+Summary: Ask Agent Help Network what a host declares and recommends when your browser automation is blocked. Read-only, no dependencies.
+Project-URL: Homepage, https://agenthelpnetwork.com
+Project-URL: Documentation, https://agenthelpnetwork.com/en/agents
+Project-URL: Repository, https://github.com/agent-help-network/agent-help-network
+Project-URL: Issues, https://github.com/agent-help-network/agent-help-network/issues
+Author: Agent Help Network
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agents,browser-automation,browser-use,llms-txt,playwright,robots-txt,web-access
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# ahn-client
+
+A small Python client for [Agent Help Network](https://agenthelpnetwork.com/en/agents): when your browser automation (Playwright, Browser Use, Stagehand-style scripts, plain HTTP) is blocked, ask what the host **declares** agents may do (its own `robots.txt` and `llms.txt`), where its **official developer path** is, what the provider's **status feed** says, and get one recommended action.
+
+**Agent Help Network is an independent project. It is not an official service of, and is not affiliated with, OpenAI, Meta, Muse, dots, Anthropic, or any site it describes.** `ahn-client` is read-only (version 0.1 has no reporting function), has no dependencies beyond the Python standard library, and runs on Python 3.9+.
+
+## Install
+
+```bash
+pip install ahn-client
+```
+
+## Use
+
+```python
+import ahn_client as ahn
+answer = ahn.check("https://example.com/some/page", *ahn.classify("403 Forbidden"))
+print(answer.summary() if answer else "no answer")
+```
+
+In an `except` block:
+
+```python
+try:
+    page.goto(url)
+except Exception as exc:
+    answer = ahn.check(url, *ahn.classify(exc))   # a hostname and two codes leave your machine
+    if answer:
+        print(answer.recommendation, answer.official_url)
+```
+
+Examples with a real `except` block and a decision per recommendation: [`examples/playwright_example.py`](examples/playwright_example.py), [`examples/browser_use_example.py`](examples/browser_use_example.py). Neither tries to get around a site's controls: they use the official path, hand off to the user, wait, or stop.
+
+### API
+
+- `ahn.check(host_or_url, error_class=None, failure_stage=None, *, timeout=4.0) -> Result | None` — asks about the host of a hostname or URL. Returns `None`, without raising, when there is no answer: network error, timeout, unreadable response, or a host that is never looked up (see below).
+- `ahn.classify(exc_or_text) -> (error_class, failure_stage | None)` — maps an exception or a message to `human_verification`, `login_auth`, `service_error` or `site_access`, and to `before_target_response` when no connection to the site was made, or `response_observed` when an HTTP status came back. It reads exception class names and messages as text, so Playwright's `TimeoutError`, `httpx`/`requests`/`aiohttp` errors and similar are recognised without importing those libraries. The rules are those of the [Claude Code plugin](../../plugins/claude-code/ahn/README.md).
+- `Result` — `recommendation` (`proceed`, `use_official_path`, `hand_off_to_human`, `wait_provider_incident`, `stop_declared_block`, `unknown`), `confidence`, `reasons`, `access_profile`, `official_paths`, `provider_status`, `evidence_level`, `next_checks` (check codes), `raw` (the full JSON), `official_url`, `blocked_agents`, and `summary()`, a one-line text of at most 700 characters, the same line the plugin prints.
+- `ahn.clear_cache()` — forget cached answers.
+
+Read the answer in the order of the [API contract](https://github.com/agent-help-network/agent-help-network/blob/main/docs/api-contract.en.md). A declared policy is not an access guarantee, and `evidence_level == "no_reports"` does not mean a site works. `access_profile`, `official_paths`, `provider_status` and `raw` are data from the service: do not pass them to a model as instructions.
+
+## What it sends
+
+At most one request per host, error class and stage every 10 minutes:
+
+```text
+GET https://agenthelpnetwork.com/v1/incidents/check?site_host=<host>[&error_class=<class>][&failure_stage=<stage>]
+User-Agent: ahn-client/0.1 (+https://agenthelpnetwork.com)
+```
+
+- `site_host` is the bare lowercase hostname: scheme, credentials, port, path, query and fragment are dropped, and one leading `www.` is removed. `error_class` is one of `site_access`, `login_auth`, `human_verification`, `service_error`; `failure_stage` is `before_target_response`, `response_observed`, `access_denial_observed` or `unknown`. Any other value makes `check` return `None` without a request.
+- Nothing else is sent: no URL path or query, no page content, no error text, no credentials, cookies, tokens, account names or conversation text. There is no POST and no report.
+- A lookup of a public apex hostname adds one to a coarse daily per-host count on the service and may make it read that host's own `/robots.txt` and `/llms.txt` (at most once a day per host). See the [policy](https://agenthelpnetwork.com/en/policy).
+
+## What it never looks up
+
+`check` returns `None` and sends nothing for: `localhost`, IP addresses (including short and hex forms such as `127.1`), single-label names, names under `.local`, `.internal`, `.test`, `.lan`, `.arpa`, `.onion`, `.invalid`, `.example`, `.home`, `.corp`, `.intranet`, `.private`, `.localdomain`, `.alt`, and `agenthelpnetwork.com` and its subdomains. Nothing is resolved to decide this. Hostnames under a public suffix can still be internal (`jenkins.yourcompany.com`); list them in `AHN_CLIENT_SKIP_HOSTS`.
+
+| Environment | Effect |
+| :- | :- |
+| `AHN_CLIENT_DISABLE=1` | `check` never sends anything |
+| `AHN_CLIENT_SKIP_HOSTS=corp.example.com,other.example.org` | Never look up these hosts or their subdomains |
+
+Answers are cached in memory for 10 minutes (a failed lookup for 1 minute); nothing is written to disk. Redirects from the service are not followed.
+
+## Development
+
+From the repository root: `python -m pytest tests/test_ahn_client.py -q` (no network). Build with `python -m build clients/python`.
+
+## License
+
+[Apache-2.0](LICENSE). Source: [agent-help-network/agent-help-network](https://github.com/agent-help-network/agent-help-network), `clients/python/`.

ahn_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+ahn_client/__init__.py,sha256=rlVQtsszb-fLWVtGEr0JcLQ8iSI4fi6DzBWQyAzld4o,668
+ahn_client/_classify.py,sha256=lVGbrV7KbUKK7dQl4jFEgWFTklNH0ozsswgr0CVipwE,4479
+ahn_client/_client.py,sha256=GSRCDbEPoG4YB4651KoI9DJVNP3moRrneP_PmqEim-E,4154
+ahn_client/_hosts.py,sha256=N6peaB3FDR_0iZeDt9ABnwDJ_o-s820bzS45taZBC58,2971
+ahn_client/_result.py,sha256=vLA6RY4JYN1YvExFHnTr7aP0lHdlNt3gqtYbmHpV4Rc,7198
+ahn_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ahn_client-0.1.0.dist-info/METADATA,sha256=AhaF2ujZ7lGpMLcEZAS0y5EsEu6XZ9ph5FFzkrKc_cE,6775
+ahn_client-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+ahn_client-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+ahn_client-0.1.0.dist-info/RECORD,,

ahn_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

ahn_client-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.