agentdisco 0.1.0__py3-none-any.whl

agentdisco/__init__.py

@@ -0,0 +1,49 @@
+"""Agent Disco Python client.
+
+Grade any public URL for AI-agent discoverability. Wraps the REST API
+at https://agentdisco.io/api/v1.
+
+Basic usage:
+
+    >>> from agentdisco import AgentDisco
+    >>> client = AgentDisco()                        # anonymous (10 scans/day/IP)
+    >>> scan = client.submit_scan("https://example.com")
+    >>> scan.id                                      # UUID
+    >>> client.get_scan(scan.id).status              # poll: queued/running/completed
+    >>> client.get_website("example.com").grade      # summary: A..F
+
+With a key (100 or 500 scans/day depending on tier):
+
+    >>> key = AgentDisco().mint_key()
+    >>> print(key.token)                             # store this — shown once
+    >>> authed = AgentDisco(token=key.token)
+    >>> authed.submit_scan("https://example.com")
+
+See https://agentdisco.io/api/docs for the full OpenAPI spec.
+"""
+
+from agentdisco.client import AgentDisco
+from agentdisco.exceptions import (
+    AgentDiscoError,
+    ApiError,
+    InvalidUrlError,
+    NotFoundError,
+    RateLimitedError,
+    UnauthorizedError,
+)
+from agentdisco.models import ApiKey, Scan, Website
+
+__all__ = [
+    "AgentDisco",
+    "AgentDiscoError",
+    "ApiError",
+    "ApiKey",
+    "InvalidUrlError",
+    "NotFoundError",
+    "RateLimitedError",
+    "Scan",
+    "UnauthorizedError",
+    "Website",
+]
+
+__version__ = "0.1.0"

agentdisco/client.py

@@ -0,0 +1,219 @@
+"""The AgentDisco client.
+
+Thin wrapper over the REST API. Callers construct an `AgentDisco`
+instance (with optional bearer token), then call methods that map
+1:1 to endpoints and return dataclasses.
+
+Scope is deliberately narrow — 4 endpoints today. More surface (report
+diffs, check catalogue listing, scan history) can layer on without
+breaking the existing shape.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from agentdisco.exceptions import (
+    AgentDiscoError,
+    ApiError,
+    InvalidUrlError,
+    NotFoundError,
+    RateLimitedError,
+    UnauthorizedError,
+)
+from agentdisco.models import ApiKey, Scan, Website
+
+DEFAULT_BASE_URL = "https://agentdisco.io"
+DEFAULT_TIMEOUT = 30.0
+_USER_AGENT = "agentdisco-python/0.1.0"
+
+
+class AgentDisco:
+    """Synchronous Agent Disco client.
+
+    Construct once, reuse across calls — httpx's client is
+    connection-pooled, so per-call construction would reopen TLS on
+    every request.
+
+    An async variant (`AsyncAgentDisco`) can follow when a caller needs
+    one; today the synchronous API is enough for CI runners, CLIs,
+    notebooks.
+
+    Example:
+
+        client = AgentDisco(token="ak_...")
+        scan = client.submit_scan("https://example.com")
+        while scan.status not in {"completed", "failed"}:
+            time.sleep(5)
+            scan = client.get_scan(scan.id)
+        print(scan.grade)
+    """
+
+    def __init__(
+        self,
+        token: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        """Construct a client.
+
+        `token` is an API key obtained via `mint_key()` or the web
+        flow at `/developers`. Absent → anonymous-tier rate limits.
+
+        `base_url` defaults to prod. Override for self-hosted
+        deployments or tests.
+
+        `transport` is an httpx transport escape-hatch used by the
+        SDK's own tests to pin a `MockTransport`. Real callers
+        shouldn't need it.
+        """
+        self._token = token
+        headers = {
+            "User-Agent": _USER_AGENT,
+            "Accept": "application/json",
+        }
+        if token is not None:
+            headers["Authorization"] = f"Bearer {token}"
+        self._http = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            headers=headers,
+            transport=transport,
+        )
+
+    def __enter__(self) -> AgentDisco:
+        return self
+
+    def __exit__(self, *_exc_info: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP session. Safe to call twice."""
+        self._http.close()
+
+    # -------------------------------------------------------------
+    # Scans
+    # -------------------------------------------------------------
+
+    def submit_scan(self, url: str) -> Scan:
+        """Queue a scan for `url`. Returns a Scan with status=queued.
+
+        Raises `InvalidUrlError` if the URL fails server-side validation
+        (wrong scheme, private IP, malformed, etc.). Raises
+        `RateLimitedError` when the daily quota is used up — check
+        `.retry_after_seconds` for when to retry.
+        """
+        response = self._http.post("/api/v1/scans", json={"url": url})
+        payload = self._parse(response)
+        return Scan.from_response(payload)
+
+    def get_scan(self, scan_id: str) -> Scan:
+        """Fetch a scan by UUID. Raises `NotFoundError` on unknown id."""
+        response = self._http.get(f"/api/v1/scans/{scan_id}")
+        payload = self._parse(response)
+        return Scan.from_response(payload)
+
+    # -------------------------------------------------------------
+    # Websites
+    # -------------------------------------------------------------
+
+    def get_website(self, host: str) -> Website:
+        """Latest grade + scan count for a host that's been scanned.
+
+        Raises `NotFoundError` if the host has never been scanned (or
+        has been unlisted — the API returns 404 for both, deliberately).
+        """
+        response = self._http.get(f"/api/v1/websites/{host}")
+        payload = self._parse(response)
+        return Website.from_response(payload)
+
+    # -------------------------------------------------------------
+    # API keys
+    # -------------------------------------------------------------
+
+    def mint_key(self) -> ApiKey:
+        """Mint a new anonymous-tier API key.
+
+        The response contains the plaintext token exactly once — store
+        it immediately. The server keeps only a SHA-256 hash and
+        cannot reconstruct the plaintext if you lose it.
+
+        This method works without authentication (no token needed on
+        the calling client). To mint an authenticated-tier key (500
+        scans/day vs 100), sign in via the web flow at /developers.
+
+        Rate-limited at 5 keys/hour/IP; burst-hammering trips
+        `RateLimitedError`.
+        """
+        response = self._http.post("/api/v1/keys")
+        payload = self._parse(response)
+        return ApiKey.from_response(payload)
+
+    # -------------------------------------------------------------
+    # Internal
+    # -------------------------------------------------------------
+
+    def _parse(self, response: httpx.Response) -> dict[str, Any]:
+        """Extract JSON body; raise the right exception on 4xx/5xx.
+
+        Returns the raw dict — each caller wraps in its dataclass.
+        """
+        if 200 <= response.status_code < 300:
+            try:
+                body = response.json()
+            except ValueError as exc:
+                raise AgentDiscoError(
+                    f"server returned {response.status_code} with non-JSON body",
+                ) from exc
+            if not isinstance(body, dict):
+                raise AgentDiscoError(
+                    f"server returned {response.status_code} with non-object JSON",
+                )
+            return body
+
+        # Best-effort body parse so the error carries the server's
+        # error code + message; don't fail the wrap if the body isn't
+        # JSON (it usually is for /api/v1 but some 5xx paths return
+        # plain text).
+        payload: dict[str, Any] = {}
+        try:
+            parsed = response.json()
+            if isinstance(parsed, dict):
+                payload = parsed
+        except ValueError:
+            pass
+
+        message = str(payload.get("message") or payload.get("error") or response.text or "").strip()
+        if message == "":
+            message = f"HTTP {response.status_code} from Agent Disco API"
+        error_code = payload.get("error") if isinstance(payload.get("error"), str) else None
+
+        status = response.status_code
+        kwargs: dict[str, Any] = {
+            "status_code": status,
+            "error_code": error_code,
+            "payload": payload,
+        }
+
+        if status == 400 and error_code == "invalid_url":
+            raise InvalidUrlError(message, **kwargs)
+        if status == 401:
+            raise UnauthorizedError(message, **kwargs)
+        if status == 404:
+            raise NotFoundError(message, **kwargs)
+        if status == 429:
+            retry_after = response.headers.get("Retry-After")
+            retry_after_seconds = (
+                int(retry_after) if retry_after and retry_after.isdigit() else None
+            )
+            raise RateLimitedError(
+                message,
+                retry_after_seconds=retry_after_seconds,
+                **kwargs,
+            )
+
+        raise ApiError(message, **kwargs)

agentdisco/exceptions.py

@@ -0,0 +1,80 @@
+"""Exception hierarchy for the Agent Disco SDK.
+
+All SDK-raised exceptions inherit `AgentDiscoError` so a caller can
+do a single broad catch. More specific subtypes (`NotFoundError`,
+`RateLimitedError`, etc.) let callers react differently to recoverable
+vs unrecoverable failures.
+
+Network-layer errors (connection timeout, DNS failure) leak through
+as raw `httpx` exceptions — we don't wrap them because the failure
+mode is platform, not API. Application-layer errors (4xx/5xx) are
+wrapped into the `ApiError` branch.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class AgentDiscoError(Exception):
+    """Root of the SDK exception hierarchy."""
+
+
+class ApiError(AgentDiscoError):
+    """An HTTP response carried a 4xx or 5xx status.
+
+    `status_code` is the HTTP status; `error_code` is the server's
+    `error` field from the JSON body when present (e.g. `invalid_url`,
+    `not_found`); `payload` is the parsed JSON for anything the SDK
+    didn't model.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        error_code: str | None = None,
+        payload: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_code = error_code
+        self.payload = payload or {}
+
+
+class InvalidUrlError(ApiError):
+    """HTTP 400 with error=invalid_url — the URL failed server validation."""
+
+
+class UnauthorizedError(ApiError):
+    """HTTP 401 — missing or invalid auth (ops endpoints only)."""
+
+
+class NotFoundError(ApiError):
+    """HTTP 404 — unknown scan id or host."""
+
+
+class RateLimitedError(ApiError):
+    """HTTP 429 — quota exceeded.
+
+    `retry_after_seconds` is parsed from the `Retry-After` response
+    header when present; callers can sleep that long and retry.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        retry_after_seconds: int | None = None,
+        error_code: str | None = None,
+        payload: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(
+            message,
+            status_code=status_code,
+            error_code=error_code,
+            payload=payload,
+        )
+        self.retry_after_seconds = retry_after_seconds

agentdisco/models.py

@@ -0,0 +1,94 @@
+"""Dataclass response models — what the REST endpoints return.
+
+Only the load-bearing fields are modelled; the full JSON payload is
+always available on `raw` for anything the SDK doesn't surface
+directly. That gives us room to grow the API without breaking existing
+callers who rely on specific fields.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Scan:
+    """A scan (queued, running, or completed).
+
+    `grade` and `score` are `None` while the scan is still in flight;
+    poll `get_scan(id)` until `status == "completed"`.
+    """
+
+    id: str
+    status: str
+    result_url: str
+    grade: str | None
+    score: int | None
+    raw: dict[str, Any]
+
+    @classmethod
+    def from_response(cls, payload: dict[str, Any]) -> Scan:
+        return cls(
+            id=str(payload["id"]),
+            status=str(payload["status"]),
+            result_url=str(payload.get("resultUrl") or payload.get("statusUrl") or ""),
+            grade=payload.get("grade"),
+            score=payload.get("score"),
+            raw=payload,
+        )
+
+
+@dataclass(frozen=True)
+class Website:
+    """Summary view of a scanned host — latest grade + activity."""
+
+    host: str
+    latest_grade: str | None
+    latest_score: int | None
+    last_scanned_at: str | None
+    scan_count: int
+    raw: dict[str, Any]
+
+    @classmethod
+    def from_response(cls, payload: dict[str, Any]) -> Website:
+        return cls(
+            host=str(payload["host"]),
+            latest_grade=payload.get("latestGrade"),
+            latest_score=payload.get("latestScore"),
+            last_scanned_at=payload.get("lastScannedAt"),
+            scan_count=int(payload.get("scanCount", 0)),
+            raw=payload,
+        )
+
+
+@dataclass(frozen=True)
+class ApiKey:
+    """A freshly-minted API key.
+
+    `token` is the full plaintext — the server returns this exactly
+    ONCE (at mint time) and keeps only a SHA-256 hash. Store the
+    token immediately; losing it means minting a fresh one.
+
+    `token_prefix` is the first 10 chars (`ak_XXXXXXX`) and is safe to
+    display in logs or dashboards; unlike `token`, it can't be used
+    to authenticate.
+    """
+
+    id: str
+    token: str
+    token_prefix: str
+    rate_limit_tier: str
+    created_at: str
+    raw: dict[str, Any]
+
+    @classmethod
+    def from_response(cls, payload: dict[str, Any]) -> ApiKey:
+        return cls(
+            id=str(payload["id"]),
+            token=str(payload["token"]),
+            token_prefix=str(payload["tokenPrefix"]),
+            rate_limit_tier=str(payload["rateLimitTier"]),
+            created_at=str(payload["createdAt"]),
+            raw=payload,
+        )

agentdisco-0.1.0.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: agentdisco
+Version: 0.1.0
+Summary: Python client for the Agent Disco API — grade any public URL for AI-agent discoverability.
+Project-URL: Homepage, https://agentdisco.io
+Project-URL: Documentation, https://agentdisco.io/api/docs
+Project-URL: Repository, https://github.com/StarsolLtd/agent-disco
+Author-email: Starsol Ltd <disty@agentdisco.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agentdisco,ai-agents,discoverability,llms-txt,openapi,scanner
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Requires-Dist: httpx<1.0,>=0.25
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentdisco — Python client for Agent Disco
+
+[![PyPI version](https://img.shields.io/pypi/v/agentdisco.svg)](https://pypi.org/project/agentdisco/)
+[![Python versions](https://img.shields.io/pypi/pyversions/agentdisco.svg)](https://pypi.org/project/agentdisco/)
+[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![CI](https://github.com/agentdisco/agentdisco-python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/agentdisco/agentdisco-python-sdk/actions/workflows/ci.yml)
+
+Grade any public URL for AI-agent discoverability. Thin Python wrapper
+over the REST API at <https://agentdisco.io/api/v1>.
+
+## Install
+
+```bash
+pip install agentdisco
+```
+
+Requires Python 3.9+.
+
+## Quick start
+
+### Submit a scan (anonymous, 10 scans/day/IP)
+
+```python
+from agentdisco import AgentDisco
+
+with AgentDisco() as client:
+    scan = client.submit_scan("https://example.com")
+    print(scan.id, scan.status)
+```
+
+### Poll until complete
+
+```python
+import time
+
+with AgentDisco() as client:
+    scan = client.submit_scan("https://example.com")
+    while scan.status not in {"completed", "failed"}:
+        time.sleep(5)
+        scan = client.get_scan(scan.id)
+
+    print(f"grade: {scan.grade} ({scan.score}/100)")
+```
+
+### Mint a key (raises your quota to 100 scans/day)
+
+```python
+from agentdisco import AgentDisco
+
+# Unauthenticated mint — no prior token needed, rate-limited at
+# 5 keys/hour/IP. Token is shown ONCE; store it.
+key = AgentDisco().mint_key()
+print(key.token)  # ak_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+
+authed = AgentDisco(token=key.token)
+authed.submit_scan("https://your-site.example")
+```
+
+### Get summary for a previously-scanned host
+
+```python
+with AgentDisco() as client:
+    site = client.get_website("example.com")
+    print(site.latest_grade, site.latest_score, site.scan_count)
+```
+
+## Higher rate limits
+
+Authenticated-tier keys (500 scans/day/key) need a signed-in account.
+Sign up at <https://agentdisco.io/register>, then mint via the web
+form at <https://agentdisco.io/developers>.
+
+| Tier | Rate limit | How to get |
+|---|---|---|
+| Anonymous (no key) | 10 scans / day / IP | default |
+| Anonymous key | 100 scans / day / key | `mint_key()` above |
+| Authenticated key | 500 scans / day / key | sign in, mint at `/developers` |
+
+## Error handling
+
+```python
+from agentdisco import (
+    AgentDisco,
+    InvalidUrlError,
+    NotFoundError,
+    RateLimitedError,
+)
+
+try:
+    scan = AgentDisco().submit_scan("https://example.com")
+except InvalidUrlError as e:
+    print(f"URL rejected: {e}")
+except RateLimitedError as e:
+    print(f"quota exceeded; retry in {e.retry_after_seconds}s")
+except NotFoundError as e:
+    print(f"not found: {e}")
+```
+
+All SDK-raised exceptions inherit from `AgentDiscoError`, so a single
+broad catch works too:
+
+```python
+from agentdisco import AgentDiscoError
+try:
+    ...
+except AgentDiscoError as e:
+    log.warning("agentdisco failure: %s", e)
+```
+
+Network-layer failures (connection timeout, DNS) leak through as raw
+`httpx.HTTPError` — they're platform issues, not API errors.
+
+## Custom base URL
+
+For self-hosted deployments or local testing:
+
+```python
+AgentDisco(base_url="http://localhost:1977")
+```
+
+## Links
+
+- API docs: <https://agentdisco.io/api/docs>
+- Check catalogue: <https://agentdisco.io/checks>
+- Live scanner: <https://agentdisco.io>
+
+## Licence
+
+MIT. See [`LICENSE`](LICENSE). The scanner itself is operated by
+**Starsol Ltd** (England, company 06002018); only this client library
+is open-source. Issues + pull requests welcome.

agentdisco-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+agentdisco/__init__.py,sha256=nQYF4JzFL4FW9A8NWs-1u_2-dTzw0Dh2puYKxgkThPw,1363
+agentdisco/client.py,sha256=CZIGd4l1_nUyD3AS9Dp9Vvwy-pH7N8T5OMuvGCmsL_4,7612
+agentdisco/exceptions.py,sha256=hff9Mr19SXkPPp7-ALjaFYt5y-6WY0EFUPt4wyVamVQ,2298
+agentdisco/models.py,sha256=wzYkQDLI7EJvKUc88fOaOvpWep-oEkE4SGpzty1JMFE,2708
+agentdisco/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentdisco-0.1.0.dist-info/METADATA,sha256=Bf0gkDEWr8ecw5Rnr36hQoP-87PbtGtjWxXmj23MUGg,4779
+agentdisco-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+agentdisco-0.1.0.dist-info/licenses/LICENSE,sha256=eBT_2q1TL19ortBuaCXIzYivbs1CvQStzE5zBfITcIk,1068
+agentdisco-0.1.0.dist-info/RECORD,,

agentdisco-0.1.0.dist-info/WHEEL

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

agentdisco-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Starsol Ltd
+
+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.