agent-ready-client 0.1.0__tar.gz

agent_ready_client-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# JS
+node_modules/
+dist/
+*.tsbuildinfo
+.npm/
+
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+build/
+*.egg-info/
+dist-python/
+.venv/
+venv/
+
+# Build outputs (python -m build writes to python/dist)
+python/dist/
+
+# OS / editor
+.DS_Store
+*.log

agent_ready_client-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agent Ready
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_ready_client-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: agent-ready-client
+Version: 0.1.0
+Summary: Official Python client SDK for the Agent Ready API — scan any URL for AI agent-readability (Vercel Agent Readability Spec, llmstxt.org, agent-protocol manifests).
+Project-URL: Homepage, https://agent-ready.dev
+Project-URL: Documentation, https://agent-ready.dev/docs/api
+Project-URL: Repository, https://github.com/mlava/agent-ready-sdk
+Project-URL: Issues, https://github.com/mlava/agent-ready-sdk/issues
+Author: Agent Ready
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aeo,agent-readability,agent-ready,ai-agents,geo,llms.txt,mcp,sdk
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# agent-ready-client (Python SDK)
+
+Official **Python** client SDK for the [Agent Ready](https://agent-ready.dev) API — scan any public URL for **AI agent-readability** against the Vercel Agent Readability Spec, the [llmstxt.org](https://llmstxt.org) standard, and agent-protocol manifests (MCP server cards, A2A, `agents.json`, `agent-permissions.json`, UCP, x402, NLWeb).
+
+Zero runtime dependencies — pure standard library (`urllib`). Python 3.8+.
+
+> Prefer the terminal? Use the [`agent-ready-scanner`](https://www.npmjs.com/package/agent-ready-scanner) CLI. Working in JS/TS? See [`agent-ready-client`](https://www.npmjs.com/package/agent-ready-client) on npm. This package is for calling the API **from your own Python code**.
+
+## Install
+
+```bash
+pip install agent-ready-client
+```
+
+## Quick start
+
+```python
+import os
+from agent_ready import AgentReady
+
+ar = AgentReady(api_key=os.environ["AGENT_READY_API_KEY"])
+
+scan = ar.scan("https://example.com")          # start + poll to completion
+print(scan["vercelScore"], scan["vercelRating"])  # 96 "excellent"
+
+for check in scan["siteChecks"]:
+    if check["status"] == "fail":
+        print(check["checkId"], check["name"], "->", check["howToFix"])
+```
+
+## Authentication
+
+`scan`, `start_scan`, `get_scan`, and `list_scans` require a **Pro API key**
+(issue one at <https://agent-ready.dev/dashboard/api-keys>). Pass it explicitly
+or set `AGENT_READY_API_KEY` in the environment:
+
+```python
+ar = AgentReady()                       # reads AGENT_READY_API_KEY
+ar = AgentReady(api_key="ar_live_...")  # or pass it in
+```
+
+`ask` is **public** and needs no key.
+
+## API
+
+```python
+AgentReady(api_key=None, base_url="https://agent-ready.dev", timeout=30.0)
+```
+
+| Method | Returns | Notes |
+| --- | --- | --- |
+| `scan(url, page_limit=None, poll_interval=2.0, timeout=120.0)` | `Scan` | Start **and poll** to completion. |
+| `start_scan(url, page_limit=None)` | `StartScanResponse` | Queue only; returns the id. |
+| `get_scan(id)` | `Scan` | Fetch a scan (running or finished). |
+| `list_scans(limit=None, cursor=None)` | `ScanListResponse` | Your scans, newest first. |
+| `ask(query, item_type=None, mode=None)` | `dict` | NLWeb doc search. **No key required.** |
+
+### Fire-and-forget + poll later
+
+```python
+started = ar.start_scan("https://example.com", page_limit=25)
+# ...later...
+scan = ar.get_scan(started["id"])
+if scan["status"] == "completed":
+    print(scan["vercelScore"])
+```
+
+### Errors
+
+Every failure raises `ApiError` with a stable `code` and (when from a response)
+an HTTP `status`:
+
+```python
+from agent_ready import ApiError
+
+try:
+    ar.scan("https://example.com")
+except ApiError as err:
+    if err.code == "rate_limited":
+        ...  # back off and retry
+```
+
+Common codes: `missing_api_key`, `unauthorized`, `subscription_required`,
+`rate_limited`, `invalid_request`, `timeout`, `network_error`.
+
+## Links
+
+- API docs & OpenAPI 3.1 spec: <https://agent-ready.dev/docs/api> · <https://agent-ready.dev/api/v1/openapi.json>
+- Methodology (all checks): <https://agent-ready.dev/methodology>
+- JS/TS SDK: <https://www.npmjs.com/package/agent-ready-client> · CLI: <https://www.npmjs.com/package/agent-ready-scanner>
+
+## License
+
+MIT © Agent Ready

agent_ready_client-0.1.0/README.md

@@ -0,0 +1,94 @@
+# agent-ready-client (Python SDK)
+
+Official **Python** client SDK for the [Agent Ready](https://agent-ready.dev) API — scan any public URL for **AI agent-readability** against the Vercel Agent Readability Spec, the [llmstxt.org](https://llmstxt.org) standard, and agent-protocol manifests (MCP server cards, A2A, `agents.json`, `agent-permissions.json`, UCP, x402, NLWeb).
+
+Zero runtime dependencies — pure standard library (`urllib`). Python 3.8+.
+
+> Prefer the terminal? Use the [`agent-ready-scanner`](https://www.npmjs.com/package/agent-ready-scanner) CLI. Working in JS/TS? See [`agent-ready-client`](https://www.npmjs.com/package/agent-ready-client) on npm. This package is for calling the API **from your own Python code**.
+
+## Install
+
+```bash
+pip install agent-ready-client
+```
+
+## Quick start
+
+```python
+import os
+from agent_ready import AgentReady
+
+ar = AgentReady(api_key=os.environ["AGENT_READY_API_KEY"])
+
+scan = ar.scan("https://example.com")          # start + poll to completion
+print(scan["vercelScore"], scan["vercelRating"])  # 96 "excellent"
+
+for check in scan["siteChecks"]:
+    if check["status"] == "fail":
+        print(check["checkId"], check["name"], "->", check["howToFix"])
+```
+
+## Authentication
+
+`scan`, `start_scan`, `get_scan`, and `list_scans` require a **Pro API key**
+(issue one at <https://agent-ready.dev/dashboard/api-keys>). Pass it explicitly
+or set `AGENT_READY_API_KEY` in the environment:
+
+```python
+ar = AgentReady()                       # reads AGENT_READY_API_KEY
+ar = AgentReady(api_key="ar_live_...")  # or pass it in
+```
+
+`ask` is **public** and needs no key.
+
+## API
+
+```python
+AgentReady(api_key=None, base_url="https://agent-ready.dev", timeout=30.0)
+```
+
+| Method | Returns | Notes |
+| --- | --- | --- |
+| `scan(url, page_limit=None, poll_interval=2.0, timeout=120.0)` | `Scan` | Start **and poll** to completion. |
+| `start_scan(url, page_limit=None)` | `StartScanResponse` | Queue only; returns the id. |
+| `get_scan(id)` | `Scan` | Fetch a scan (running or finished). |
+| `list_scans(limit=None, cursor=None)` | `ScanListResponse` | Your scans, newest first. |
+| `ask(query, item_type=None, mode=None)` | `dict` | NLWeb doc search. **No key required.** |
+
+### Fire-and-forget + poll later
+
+```python
+started = ar.start_scan("https://example.com", page_limit=25)
+# ...later...
+scan = ar.get_scan(started["id"])
+if scan["status"] == "completed":
+    print(scan["vercelScore"])
+```
+
+### Errors
+
+Every failure raises `ApiError` with a stable `code` and (when from a response)
+an HTTP `status`:
+
+```python
+from agent_ready import ApiError
+
+try:
+    ar.scan("https://example.com")
+except ApiError as err:
+    if err.code == "rate_limited":
+        ...  # back off and retry
+```
+
+Common codes: `missing_api_key`, `unauthorized`, `subscription_required`,
+`rate_limited`, `invalid_request`, `timeout`, `network_error`.
+
+## Links
+
+- API docs & OpenAPI 3.1 spec: <https://agent-ready.dev/docs/api> · <https://agent-ready.dev/api/v1/openapi.json>
+- Methodology (all checks): <https://agent-ready.dev/methodology>
+- JS/TS SDK: <https://www.npmjs.com/package/agent-ready-client> · CLI: <https://www.npmjs.com/package/agent-ready-scanner>
+
+## License
+
+MIT © Agent Ready

agent_ready_client-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agent-ready-client"
+version = "0.1.0"
+description = "Official Python client SDK for the Agent Ready API — scan any URL for AI agent-readability (Vercel Agent Readability Spec, llmstxt.org, agent-protocol manifests)."
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Agent Ready" }]
+keywords = [
+  "agent-ready",
+  "agent-readability",
+  "llms.txt",
+  "mcp",
+  "ai-agents",
+  "sdk",
+  "aeo",
+  "geo",
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Developers",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://agent-ready.dev"
+Documentation = "https://agent-ready.dev/docs/api"
+Repository = "https://github.com/mlava/agent-ready-sdk"
+Issues = "https://github.com/mlava/agent-ready-sdk/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent_ready"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md", "LICENSE"]

agent_ready_client-0.1.0/src/agent_ready/__init__.py

@@ -0,0 +1,27 @@
+"""Official Python client SDK for the Agent Ready API.
+
+See https://agent-ready.dev/docs/api for the full API reference.
+"""
+
+from .client import (
+    AgentReady,
+    ApiError,
+    CheckResult,
+    Scan,
+    ScanListResponse,
+    ScanSummary,
+    StartScanResponse,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AgentReady",
+    "ApiError",
+    "CheckResult",
+    "Scan",
+    "ScanListResponse",
+    "ScanSummary",
+    "StartScanResponse",
+    "__version__",
+]

agent_ready_client-0.1.0/src/agent_ready/client.py

@@ -0,0 +1,296 @@
+"""Official Python client SDK for the Agent Ready API.
+
+Scan any public URL for AI agent-readability against the Vercel Agent
+Readability Spec, the llmstxt.org standard, and agent-protocol manifests.
+
+    from agent_ready import AgentReady
+    ar = AgentReady(api_key="ar_live_...")
+    scan = ar.scan("https://example.com")
+    print(scan["vercelScore"], scan["vercelRating"])
+
+Zero runtime dependencies — uses only the standard library (``urllib``).
+Mirrors the transport in the ``agent-ready-client`` (JS) and ``agent-ready-cli``
+packages so behaviour stays consistent across surfaces.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, List, Optional
+
+try:  # TypedDict is in typing on 3.8+, but keep the import defensive.
+    from typing import TypedDict
+except ImportError:  # pragma: no cover
+    TypedDict = None  # type: ignore[assignment]
+
+__all__ = [
+    "AgentReady",
+    "ApiError",
+    "CheckResult",
+    "Scan",
+    "ScanSummary",
+    "ScanListResponse",
+    "StartScanResponse",
+]
+
+DEFAULT_BASE_URL = "https://agent-ready.dev"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_SCAN_TIMEOUT = 120.0
+DEFAULT_POLL_INTERVAL = 2.0
+
+
+class ApiError(Exception):
+    """Raised for every API, network, and timeout failure.
+
+    Attributes:
+        code: Stable machine code (e.g. ``"unauthorized"``, ``"rate_limited"``,
+            ``"timeout"``).
+        status: HTTP status when the failure came from a response, else ``None``.
+    """
+
+    def __init__(self, code: str, message: str, status: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status = status
+
+    def __str__(self) -> str:
+        message = super().__str__()
+        return f"[{self.code}] {message}" if self.code else message
+
+
+if TypedDict is not None:
+
+    class CheckResult(TypedDict):
+        checkId: str
+        name: str
+        status: str  # "pass" | "fail" | "warn" | "error"
+        message: str
+        howToFix: Optional[str]
+        details: Dict[str, Any]
+
+    class _PageResult(TypedDict):
+        url: str
+        checks: List[CheckResult]
+
+    class Scan(TypedDict, total=False):
+        id: str
+        rootUrl: str
+        status: str  # "running" | "completed" | "failed"
+        createdAt: str
+        completedAt: Optional[str]
+        pagesDiscovered: int
+        pagesScanned: int
+        vercelScore: int
+        vercelRating: str
+        llmstxtScore: int
+        siteChecks: List[CheckResult]
+        llmstxtChecks: List[CheckResult]
+        pageResults: List[_PageResult]
+        shareToken: str
+
+    class StartScanResponse(TypedDict):
+        id: str
+        status: str
+        url: str
+        pollUrl: str
+
+    class ScanSummary(TypedDict):
+        id: str
+        shareToken: str
+        domain: str
+        rootUrl: str
+        vercelScore: Optional[int]
+        vercelRating: Optional[str]
+        llmstxtScore: Optional[int]
+        pagesScanned: Optional[int]
+        createdAt: str
+
+    class ScanListResponse(TypedDict, total=False):
+        data: List[ScanSummary]
+        nextCursor: str
+else:  # pragma: no cover - typing fallback for very old runtimes
+    CheckResult = Dict[str, Any]  # type: ignore[misc,assignment]
+    Scan = Dict[str, Any]  # type: ignore[misc,assignment]
+    StartScanResponse = Dict[str, Any]  # type: ignore[misc,assignment]
+    ScanSummary = Dict[str, Any]  # type: ignore[misc,assignment]
+    ScanListResponse = Dict[str, Any]  # type: ignore[misc,assignment]
+
+
+class AgentReady:
+    """Client for the Agent Ready REST API. Stateless and reusable."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        key = api_key if api_key is not None else os.environ.get("AGENT_READY_API_KEY")
+        self.api_key: Optional[str] = (key or "").strip() or None
+        self.base_url: str = base_url.rstrip("/")
+        self.timeout: float = timeout
+
+    def start_scan(
+        self, url: str, page_limit: Optional[int] = None
+    ) -> "StartScanResponse":
+        """Start a scan and return immediately (does not wait for completion)."""
+        body: Dict[str, Any] = {"url": url}
+        if page_limit is not None:
+            body["pageLimit"] = page_limit
+        return self._request("POST", "/api/v1/scans", body=body)
+
+    def get_scan(self, scan_id: str) -> "Scan":
+        """Fetch a scan (running or finished) by id."""
+        return self._request(
+            "GET", "/api/v1/scans/" + urllib.parse.quote(scan_id, safe="")
+        )
+
+    def scan(
+        self,
+        url: str,
+        page_limit: Optional[int] = None,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+        timeout: float = DEFAULT_SCAN_TIMEOUT,
+    ) -> "Scan":
+        """Start a scan and poll until it completes, returning the full result.
+
+        Raises ``ApiError("timeout")`` if it is still running past ``timeout``
+        seconds — the scan keeps running server-side, so re-fetch it later with
+        :meth:`get_scan` using the id from the error message.
+        """
+        started = self.start_scan(url, page_limit=page_limit)
+        deadline = time.monotonic() + timeout
+        while True:
+            result = self.get_scan(started["id"])
+            if result.get("status") != "running":
+                return result
+            if time.monotonic() >= deadline:
+                raise ApiError(
+                    "timeout",
+                    "Scan {0} still running past the wait budget. "
+                    "Re-fetch it with get_scan({0!r}).".format(started["id"]),
+                )
+            time.sleep(poll_interval)
+
+    def list_scans(
+        self, limit: Optional[int] = None, cursor: Optional[str] = None
+    ) -> "ScanListResponse":
+        """List your scans, newest first."""
+        params: Dict[str, str] = {}
+        if limit is not None:
+            params["limit"] = str(limit)
+        if cursor:
+            params["cursor"] = cursor
+        path = "/api/v1/scans"
+        if params:
+            path += "?" + urllib.parse.urlencode(params)
+        return self._request("GET", path)
+
+    def ask(
+        self,
+        query: str,
+        item_type: Optional[str] = None,
+        mode: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Natural-language search over Agent Ready's docs (NLWeb ``/ask``).
+
+        Public — no API key required. Returns the ``_meta`` envelope as-is,
+        including for no-results (404) and rate-limited (429) responses.
+        """
+        body: Dict[str, Any] = {"query": {"q": query, "itemType": item_type}}
+        if mode:
+            body["prefer"] = {"mode": mode}
+        return self._request(
+            "POST",
+            "/api/v1/ask",
+            body=body,
+            require_key=False,
+            pass_envelope_on_error=True,
+        )
+
+    # ---- transport ----------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Dict[str, Any]] = None,
+        require_key: bool = True,
+        pass_envelope_on_error: bool = False,
+    ) -> Any:
+        if require_key and not self.api_key:
+            raise ApiError(
+                "missing_api_key",
+                "No API key set. Issue a Pro key at "
+                "https://agent-ready.dev/dashboard/api-keys and pass api_key= "
+                "or set AGENT_READY_API_KEY.",
+            )
+
+        headers: Dict[str, str] = {"Accept": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = "Bearer " + self.api_key
+        data: Optional[bytes] = None
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+
+        req = urllib.request.Request(
+            self.base_url + path, data=data, headers=headers, method=method
+        )
+
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                status = resp.status
+                text = resp.read().decode("utf-8")
+        except urllib.error.HTTPError as err:
+            status = err.code
+            text = err.read().decode("utf-8", "replace")
+        except (socket.timeout, TimeoutError) as err:
+            raise ApiError(
+                "timeout",
+                "Request to {0} timed out after {1}s.".format(path, self.timeout),
+            ) from err
+        except urllib.error.URLError as err:
+            reason = err.reason
+            if isinstance(reason, (socket.timeout, TimeoutError)):
+                raise ApiError(
+                    "timeout",
+                    "Request to {0} timed out after {1}s.".format(path, self.timeout),
+                ) from err
+            raise ApiError(
+                "network_error",
+                "Network error calling {0}: {1}".format(path, reason),
+            ) from err
+
+        payload: Any = None
+        if text:
+            try:
+                payload = json.loads(text)
+            except json.JSONDecodeError:
+                payload = None
+
+        # `/ask` answers and failures both carry a `_meta` envelope; pass through.
+        if (
+            pass_envelope_on_error
+            and isinstance(payload, dict)
+            and "_meta" in payload
+        ):
+            return payload
+
+        if status < 200 or status >= 300:
+            detail = payload.get("error") if isinstance(payload, dict) else None
+            code = detail.get("code") if isinstance(detail, dict) else None
+            message = detail.get("message") if isinstance(detail, dict) else None
+            raise ApiError(
+                code or "http_{0}".format(status),
+                message or text or "HTTP {0} from {1}".format(status, path),
+                status,
+            )
+
+        return payload