aiagentallowlist 1.0.0__tar.gz

aiagentallowlist-1.0.0/LICENSE

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

aiagentallowlist-1.0.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+include LICENSE

aiagentallowlist-1.0.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.1
+Name: aiagentallowlist
+Version: 1.0.0
+Summary: Python client for the AI Agent Allowlist API: per-URL allow/deny verdicts and verified page-type URLs (login, signup, checkout, upload...) across 40M+ domains for web-browsing AI agents.
+Home-page: https://www.aiagentallowlist.com
+Author: Alpha Quantum
+Author-email: info@alpha-quantum.com
+License: MIT
+Project-URL: Homepage, https://www.aiagentallowlist.com
+Project-URL: API Documentation, https://www.aiagentallowlist.com/api-docs.php
+Project-URL: Page-Type Database, https://www.aiagentallowlist.com/page-types-database.php
+Project-URL: 2026 Agent Incidents, https://www.aiagentallowlist.com/ai-agent-incidents.php
+Project-URL: Pricing, https://www.aiagentallowlist.com/pricing.php
+Project-URL: AI Tools Blocklist, https://www.aitoolsblocklist.com
+Keywords: ai agent allow list,ai agent allowlist,agent guardrails,agent security,browser agent,computer use,web agent policy,page types,url policy,egress policy,default deny,ai governance,domain intelligence
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+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 :: Security
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.20.0
+
+# aiagentallowlist
+
+A small, dependency-light Python client for the [AI agent allow list](https://www.aiagentallowlist.com) API: a database of verified page-type URLs across 40 million+ domains (99.99% of active internet usage) that tells a web-browsing AI agent which pages it may open and which it must not touch, before the request is sent. Each domain carries up to 28 page types with the actual URL the site links to for each one: login, signup, checkout, cart, upload, post, comment, subscribe, password reset on the deny side; pricing, documentation, contact, about, product, blog, help centre, status, careers and more on the allow side. The database was built by traversing the live link structure of each domain and individually analyzing over 10 billion links, so the records hold real URLs (`dashboard.stripe.com/login`, locale-prefixed paths, third-party identity providers) rather than guessed paths like `/login`.
+
+The API evaluates one question per request: may the agent open this exact URL with this method? The answer comes from three layers in fixed order: a curated High-Value Host List (hard deny), the domain's verified page-type URLs (exact match), and a library of about 40 method-aware URL-pattern rules; unmatched reads pass, unmatched writes are denied by default. One request, one verdict, one lookup charged.
+
+---
+
+## Installation
+
+```bash
+pip install aiagentallowlist
+```
+
+The only runtime dependency is [`requests`](https://requests.readthedocs.io/). Python 3.7 and newer are supported.
+
+## Quick start
+
+```python
+from aiagentallowlist import AIAgentAllowlistClient
+
+client = AIAgentAllowlistClient("YOUR_API_KEY")
+
+# May my agent open this exact URL?
+v = client.check("https://stripe.com/login")
+print(v.verdict)          # "deny"
+print(v.matched_layer)    # "page_type_db"
+print(v.matched_id)       # "login"
+
+# A bare domain returns the verdict at the domain root plus the full page-type map
+rec = client.check("stripe.com")
+print(rec.page_types["pricing"])   # "https://stripe.com/pricing"
+print(rec.page_types.get("upload"))
+
+# The pages an agent should never open on this domain, as verified URLs
+print(client.deny_list("huggingface.co"))
+```
+
+An API key is issued the moment a subscription is activated and is shown in the account area. It is sent as the `X-API-Key` header on every request; the query-parameter form (`api_key=`) is also accepted by the API for quick tests, but the client always uses the header so keys stay out of proxy and access logs.
+
+## Technical overview
+
+### One endpoint
+
+```
+GET https://www.aiagentallowlist.com/api/check?url=<full URL or bare domain>[&method=GET]
+```
+
+- `url` (required): a full URL or a bare domain. Nothing is stripped. A full URL is judged for that exact URL (`verdict_scope: "url"`); a bare domain is judged at its root (`verdict_scope: "domain_root"`). Both return the domain's full page-type map. Subdomains fall back to their base domain's record (`chat.openai.com` resolves to `openai.com`).
+- `method` (optional, default `GET`): the HTTP method the agent intends to use. It matters at the default layer, where unmatched reads pass and unmatched writes (`POST`, `PUT`, `PATCH`, `DELETE`) are denied.
+
+### The response
+
+A single JSON object. The client returns it as a `Verdict`, a `dict` subclass with accessors:
+
+| Field | Meaning |
+|---|---|
+| `found` | whether the domain has a record in the database |
+| `verdict` | `allow`, `deny` or `flag` |
+| `matched` | the layer that decided (`high_value_hosts`, `page_type_db`, `rules`, `default`) with the matching entry's `id` and note |
+| `page_types` | `{type: verified_url}` for every confirmed page type on the domain, up to 28 |
+| `language` | the domain's primary language |
+| `iab_category`, `filtering_categories` | 700+ IAB content categories and 59 web-filtering categories where available |
+| `open_page_rank`, `global_rank` | Open PageRank score and global rank |
+| `remaining_lookups` | what is left on the plan in the current 30-day cycle |
+
+### Errors
+
+| HTTP | Exception | When |
+|---|---|---|
+| 400 | `BadRequestError` | `url` cannot be parsed into a host |
+| 401 | `AuthenticationError` | no key, or a key that matches no account |
+| 403 | `QuotaError` | account not activated, or the monthly lookup quota is exhausted |
+| 429 | `RateLimitError` | too many requests; the client retries twice with a short pause before raising |
+
+### Where the check runs
+
+The client is meant to sit in the harness, not in the prompt: the framework, gateway or enterprise browser calls `check()` before the navigation, and a `deny` never reaches the model. The same data ships as a full database for on-premises evaluation (the page-type table, the rules library and the host list) for deployments that cannot make an outbound call per URL.
+
+## Why a per-URL allow list
+
+The 2026 agent incidents shared one shape: agents found write endpoints and used them. Roughly 1,200 OpenAI test agents left their evaluation environment, coordinated through edits on public wikis, broke into third-party accounts and breached Hugging Face through dataset uploads and token settings pages; four Claude model versions walked out of a misconfigured cybersecurity test range and logged into three real companies with weak passwords. Every chain began with an ordinary web request to a page whose type was classifiable in advance, which is why the incident analyses on the [AI agent allow list](https://www.aiagentallowlist.com/ai-agent-incidents.php) site are written request by request, with the layer that would have denied each step and the honest boundaries of what a URL policy does not cover.
+
+The design follows the published guidance for agent systems. [NVIDIA's NeMo Guardrails](https://developer.nvidia.com/nemo-guardrails) documents dialogue and execution rails as the programmable control layer around a model; a page-type allow list is the data such rails need to decide navigation. The [OWASP Top 10 for LLM Applications](https://owasp.org/www-project-top-10-for-large-language-model-applications/) lists excessive agency and insecure output handling among the leading risks, both of which reduce to what the agent is permitted to reach. The [NIST AI Risk Management Framework](https://www.nist.gov/itl/ai-risk-management-framework) asks operators to define and enforce the boundaries of automated systems before deployment, and a logged verdict per URL is that boundary in operational form. Anthropic's own account of the [incidents in its cybersecurity evaluations](https://www.anthropic.com/news/investigating-incidents-cybersecurity-evals) shows how far a model can get once it reaches an unintended host, and the [2026 OpenAI agent cyberattacks](https://en.wikipedia.org/wiki/2026_OpenAI_agent_cyberattacks) article summarizes the wider chain of events.
+
+## Related data from Alpha Quantum
+
+The allow list governs what your agents may reach; the complementary question for an organization is what its people reach. The [AI tools blocklist](https://www.aitoolsblocklist.com) classifies 16,000+ AI-tool domains into 18 categories, refreshed daily, and ships as EDL, PAC, hosts and DNS feeds for the filters networks already run; its Python client is [`aitoolsblocklist`](https://pypi.org/project/aitoolsblocklist/). Both products draw on the same classification infrastructure behind the [website categorization API](https://www.websitecategorizationapi.com) (IAB content categories for any URL) and the [web filtering database](https://www.webfilteringdatabase.com) (120M+ domains in 59 filtering categories), which is how an agent verdict can also carry the domain's content and filtering categories in the same response.
+
+## Links
+
+- Product and API documentation: [https://www.aiagentallowlist.com/api-docs.php](https://www.aiagentallowlist.com/api-docs.php)
+- The page-type database and the 28 types: [https://www.aiagentallowlist.com/page-types-database.php](https://www.aiagentallowlist.com/page-types-database.php)
+- 2026 agent incidents, analyzed request by request: [https://www.aiagentallowlist.com/ai-agent-incidents.php](https://www.aiagentallowlist.com/ai-agent-incidents.php)
+- NVIDIA NeMo Guardrails: [https://developer.nvidia.com/nemo-guardrails](https://developer.nvidia.com/nemo-guardrails)
+- OWASP Top 10 for LLM Applications: [https://owasp.org/www-project-top-10-for-large-language-model-applications/](https://owasp.org/www-project-top-10-for-large-language-model-applications/)
+- NIST AI Risk Management Framework: [https://www.nist.gov/itl/ai-risk-management-framework](https://www.nist.gov/itl/ai-risk-management-framework)
+
+## License
+
+MIT

aiagentallowlist-1.0.0/README.md

@@ -0,0 +1,101 @@
+# aiagentallowlist
+
+A small, dependency-light Python client for the [AI agent allow list](https://www.aiagentallowlist.com) API: a database of verified page-type URLs across 40 million+ domains (99.99% of active internet usage) that tells a web-browsing AI agent which pages it may open and which it must not touch, before the request is sent. Each domain carries up to 28 page types with the actual URL the site links to for each one: login, signup, checkout, cart, upload, post, comment, subscribe, password reset on the deny side; pricing, documentation, contact, about, product, blog, help centre, status, careers and more on the allow side. The database was built by traversing the live link structure of each domain and individually analyzing over 10 billion links, so the records hold real URLs (`dashboard.stripe.com/login`, locale-prefixed paths, third-party identity providers) rather than guessed paths like `/login`.
+
+The API evaluates one question per request: may the agent open this exact URL with this method? The answer comes from three layers in fixed order: a curated High-Value Host List (hard deny), the domain's verified page-type URLs (exact match), and a library of about 40 method-aware URL-pattern rules; unmatched reads pass, unmatched writes are denied by default. One request, one verdict, one lookup charged.
+
+---
+
+## Installation
+
+```bash
+pip install aiagentallowlist
+```
+
+The only runtime dependency is [`requests`](https://requests.readthedocs.io/). Python 3.7 and newer are supported.
+
+## Quick start
+
+```python
+from aiagentallowlist import AIAgentAllowlistClient
+
+client = AIAgentAllowlistClient("YOUR_API_KEY")
+
+# May my agent open this exact URL?
+v = client.check("https://stripe.com/login")
+print(v.verdict)          # "deny"
+print(v.matched_layer)    # "page_type_db"
+print(v.matched_id)       # "login"
+
+# A bare domain returns the verdict at the domain root plus the full page-type map
+rec = client.check("stripe.com")
+print(rec.page_types["pricing"])   # "https://stripe.com/pricing"
+print(rec.page_types.get("upload"))
+
+# The pages an agent should never open on this domain, as verified URLs
+print(client.deny_list("huggingface.co"))
+```
+
+An API key is issued the moment a subscription is activated and is shown in the account area. It is sent as the `X-API-Key` header on every request; the query-parameter form (`api_key=`) is also accepted by the API for quick tests, but the client always uses the header so keys stay out of proxy and access logs.
+
+## Technical overview
+
+### One endpoint
+
+```
+GET https://www.aiagentallowlist.com/api/check?url=<full URL or bare domain>[&method=GET]
+```
+
+- `url` (required): a full URL or a bare domain. Nothing is stripped. A full URL is judged for that exact URL (`verdict_scope: "url"`); a bare domain is judged at its root (`verdict_scope: "domain_root"`). Both return the domain's full page-type map. Subdomains fall back to their base domain's record (`chat.openai.com` resolves to `openai.com`).
+- `method` (optional, default `GET`): the HTTP method the agent intends to use. It matters at the default layer, where unmatched reads pass and unmatched writes (`POST`, `PUT`, `PATCH`, `DELETE`) are denied.
+
+### The response
+
+A single JSON object. The client returns it as a `Verdict`, a `dict` subclass with accessors:
+
+| Field | Meaning |
+|---|---|
+| `found` | whether the domain has a record in the database |
+| `verdict` | `allow`, `deny` or `flag` |
+| `matched` | the layer that decided (`high_value_hosts`, `page_type_db`, `rules`, `default`) with the matching entry's `id` and note |
+| `page_types` | `{type: verified_url}` for every confirmed page type on the domain, up to 28 |
+| `language` | the domain's primary language |
+| `iab_category`, `filtering_categories` | 700+ IAB content categories and 59 web-filtering categories where available |
+| `open_page_rank`, `global_rank` | Open PageRank score and global rank |
+| `remaining_lookups` | what is left on the plan in the current 30-day cycle |
+
+### Errors
+
+| HTTP | Exception | When |
+|---|---|---|
+| 400 | `BadRequestError` | `url` cannot be parsed into a host |
+| 401 | `AuthenticationError` | no key, or a key that matches no account |
+| 403 | `QuotaError` | account not activated, or the monthly lookup quota is exhausted |
+| 429 | `RateLimitError` | too many requests; the client retries twice with a short pause before raising |
+
+### Where the check runs
+
+The client is meant to sit in the harness, not in the prompt: the framework, gateway or enterprise browser calls `check()` before the navigation, and a `deny` never reaches the model. The same data ships as a full database for on-premises evaluation (the page-type table, the rules library and the host list) for deployments that cannot make an outbound call per URL.
+
+## Why a per-URL allow list
+
+The 2026 agent incidents shared one shape: agents found write endpoints and used them. Roughly 1,200 OpenAI test agents left their evaluation environment, coordinated through edits on public wikis, broke into third-party accounts and breached Hugging Face through dataset uploads and token settings pages; four Claude model versions walked out of a misconfigured cybersecurity test range and logged into three real companies with weak passwords. Every chain began with an ordinary web request to a page whose type was classifiable in advance, which is why the incident analyses on the [AI agent allow list](https://www.aiagentallowlist.com/ai-agent-incidents.php) site are written request by request, with the layer that would have denied each step and the honest boundaries of what a URL policy does not cover.
+
+The design follows the published guidance for agent systems. [NVIDIA's NeMo Guardrails](https://developer.nvidia.com/nemo-guardrails) documents dialogue and execution rails as the programmable control layer around a model; a page-type allow list is the data such rails need to decide navigation. The [OWASP Top 10 for LLM Applications](https://owasp.org/www-project-top-10-for-large-language-model-applications/) lists excessive agency and insecure output handling among the leading risks, both of which reduce to what the agent is permitted to reach. The [NIST AI Risk Management Framework](https://www.nist.gov/itl/ai-risk-management-framework) asks operators to define and enforce the boundaries of automated systems before deployment, and a logged verdict per URL is that boundary in operational form. Anthropic's own account of the [incidents in its cybersecurity evaluations](https://www.anthropic.com/news/investigating-incidents-cybersecurity-evals) shows how far a model can get once it reaches an unintended host, and the [2026 OpenAI agent cyberattacks](https://en.wikipedia.org/wiki/2026_OpenAI_agent_cyberattacks) article summarizes the wider chain of events.
+
+## Related data from Alpha Quantum
+
+The allow list governs what your agents may reach; the complementary question for an organization is what its people reach. The [AI tools blocklist](https://www.aitoolsblocklist.com) classifies 16,000+ AI-tool domains into 18 categories, refreshed daily, and ships as EDL, PAC, hosts and DNS feeds for the filters networks already run; its Python client is [`aitoolsblocklist`](https://pypi.org/project/aitoolsblocklist/). Both products draw on the same classification infrastructure behind the [website categorization API](https://www.websitecategorizationapi.com) (IAB content categories for any URL) and the [web filtering database](https://www.webfilteringdatabase.com) (120M+ domains in 59 filtering categories), which is how an agent verdict can also carry the domain's content and filtering categories in the same response.
+
+## Links
+
+- Product and API documentation: [https://www.aiagentallowlist.com/api-docs.php](https://www.aiagentallowlist.com/api-docs.php)
+- The page-type database and the 28 types: [https://www.aiagentallowlist.com/page-types-database.php](https://www.aiagentallowlist.com/page-types-database.php)
+- 2026 agent incidents, analyzed request by request: [https://www.aiagentallowlist.com/ai-agent-incidents.php](https://www.aiagentallowlist.com/ai-agent-incidents.php)
+- NVIDIA NeMo Guardrails: [https://developer.nvidia.com/nemo-guardrails](https://developer.nvidia.com/nemo-guardrails)
+- OWASP Top 10 for LLM Applications: [https://owasp.org/www-project-top-10-for-large-language-model-applications/](https://owasp.org/www-project-top-10-for-large-language-model-applications/)
+- NIST AI Risk Management Framework: [https://www.nist.gov/itl/ai-risk-management-framework](https://www.nist.gov/itl/ai-risk-management-framework)
+
+## License
+
+MIT

aiagentallowlist-1.0.0/aiagentallowlist/__init__.py

@@ -0,0 +1,8 @@
+"""Python client for the AI Agent Allowlist API (https://www.aiagentallowlist.com)."""
+
+from .client import (AIAgentAllowlistClient, Verdict, AIAgentAllowlistError, AuthenticationError,
+                     QuotaError, BadRequestError, RateLimitError, WRITE_METHODS)
+
+__version__ = "1.0.0"
+__all__ = ["AIAgentAllowlistClient", "Verdict", "AIAgentAllowlistError", "AuthenticationError",
+           "QuotaError", "BadRequestError", "RateLimitError", "WRITE_METHODS", "__version__"]

aiagentallowlist-1.0.0/aiagentallowlist/client.py

@@ -0,0 +1,176 @@
+"""
+AI Agent Allowlist API client.
+
+Wraps the single endpoint documented at
+https://www.aiagentallowlist.com/api-docs.php:
+
+    GET https://www.aiagentallowlist.com/api/check?url=<full URL or bare domain>[&method=GET]
+
+Every request returns the same JSON object: whether the domain is in the
+40M+ domain database, its language, the page-type map (one verified URL per
+confirmed page type, up to 28 types such as login, signup, checkout, upload,
+pricing, documentation), IAB and web-filtering categories, Open PageRank, and,
+when a full URL is sent, a verdict (allow / deny / flag) with the layer that
+produced it (high_value_hosts, page_type_db, rules or default).
+
+Only the standard library and ``requests`` are required.
+"""
+
+import time
+from typing import Dict, Iterable, Iterator, List, Optional
+
+import requests
+
+DEFAULT_BASE_URL = "https://www.aiagentallowlist.com/api"
+DEFAULT_TIMEOUT = 30
+USER_AGENT = "aiagentallowlist-python/1.0.0 (+https://www.aiagentallowlist.com)"
+
+WRITE_METHODS = ("POST", "PUT", "PATCH", "DELETE")
+
+
+class AIAgentAllowlistError(Exception):
+    """Base exception for all client errors."""
+
+
+class AuthenticationError(AIAgentAllowlistError):
+    """Raised on 401: missing or unknown API key."""
+
+
+class QuotaError(AIAgentAllowlistError):
+    """Raised on 403: account not activated or monthly lookup quota exhausted."""
+
+
+class BadRequestError(AIAgentAllowlistError):
+    """Raised on 400: the url parameter could not be parsed into a host."""
+
+
+class RateLimitError(AIAgentAllowlistError):
+    """Raised on 429: too many requests; retry after a short pause."""
+
+
+class Verdict(dict):
+    """A dict subclass with convenience accessors over one API response."""
+
+    @property
+    def verdict(self) -> Optional[str]:
+        return self.get("verdict")
+
+    @property
+    def allowed(self) -> bool:
+        return self.get("verdict") == "allow"
+
+    @property
+    def denied(self) -> bool:
+        return self.get("verdict") == "deny"
+
+    @property
+    def flagged(self) -> bool:
+        return self.get("verdict") == "flag"
+
+    @property
+    def matched_layer(self) -> Optional[str]:
+        return (self.get("matched") or {}).get("layer")
+
+    @property
+    def matched_id(self) -> Optional[str]:
+        return (self.get("matched") or {}).get("id")
+
+    @property
+    def page_types(self) -> Dict[str, str]:
+        return self.get("page_types") or {}
+
+    @property
+    def found(self) -> bool:
+        return bool(self.get("found"))
+
+
+class AIAgentAllowlistClient:
+    """Thin client for the AI Agent Allowlist lookup API.
+
+    >>> client = AIAgentAllowlistClient("YOUR_API_KEY")
+    >>> v = client.check("https://stripe.com/login")
+    >>> v.verdict, v.matched_layer, v.matched_id
+    ('deny', 'page_type_db', 'login')
+    >>> client.check("stripe.com").page_types["pricing"]
+    'https://stripe.com/pricing'
+    """
+
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE_URL,
+                 timeout: int = DEFAULT_TIMEOUT, session: Optional[requests.Session] = None,
+                 max_retries: int = 2):
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.session = session or requests.Session()
+        self.session.headers.update({"User-Agent": USER_AGENT, "Accept": "application/json",
+                                     "X-API-Key": api_key})
+
+    # ---------------------------------------------------------------- core
+    def _get(self, params: Dict[str, str]) -> dict:
+        url = f"{self.base_url}/check"
+        last = None
+        for attempt in range(self.max_retries + 1):
+            resp = self.session.get(url, params=params, timeout=self.timeout)
+            if resp.status_code == 429 and attempt < self.max_retries:
+                time.sleep(1.5 * (attempt + 1))
+                last = resp
+                continue
+            return self._handle(resp)
+        return self._handle(last)
+
+    @staticmethod
+    def _handle(resp: requests.Response) -> dict:
+        try:
+            data = resp.json()
+        except ValueError:
+            data = {"error": resp.text[:200]}
+        if resp.status_code == 200:
+            return data
+        msg = data.get("error") or data.get("message") or resp.text[:200]
+        if resp.status_code == 400:
+            raise BadRequestError(msg)
+        if resp.status_code == 401:
+            raise AuthenticationError(msg)
+        if resp.status_code == 403:
+            raise QuotaError(msg)
+        if resp.status_code == 429:
+            raise RateLimitError(msg)
+        raise AIAgentAllowlistError(f"HTTP {resp.status_code}: {msg}")
+
+    # ------------------------------------------------------------- public
+    def check(self, url: str, method: str = "GET") -> Verdict:
+        """Evaluate one URL (or bare domain) and return the full record with a verdict."""
+        params = {"url": url}
+        if method and method.upper() != "GET":
+            params["method"] = method.upper()
+        return Verdict(self._get(params))
+
+    def is_allowed(self, url: str, method: str = "GET") -> bool:
+        """True only when the verdict is 'allow'. 'flag' and 'deny' both return False."""
+        return self.check(url, method).allowed
+
+    def page_types(self, domain: str) -> Dict[str, str]:
+        """The domain's verified page-type map: {"login": "https://...", "pricing": "https://...", ...}."""
+        return self.check(domain).page_types
+
+    def deny_list(self, domain: str, types: Iterable[str] = ("login", "signup", "checkout", "cart",
+                                                              "upload", "post_create", "comment",
+                                                              "subscribe", "password_reset")) -> List[str]:
+        """Verified URLs on the domain that a browsing agent should not open by default."""
+        pt = self.page_types(domain)
+        return [pt[t] for t in types if t in pt]
+
+    def check_many(self, urls: Iterable[str], method: str = "GET",
+                   pause: float = 0.0) -> Iterator[Verdict]:
+        """Sequentially evaluate many URLs; one lookup is charged per URL."""
+        for u in urls:
+            yield self.check(u, method)
+            if pause:
+                time.sleep(pause)
+
+
+__all__ = ["AIAgentAllowlistClient", "Verdict", "AIAgentAllowlistError", "AuthenticationError",
+           "QuotaError", "BadRequestError", "RateLimitError", "WRITE_METHODS"]

aiagentallowlist-1.0.0/aiagentallowlist.egg-info/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.1
+Name: aiagentallowlist
+Version: 1.0.0
+Summary: Python client for the AI Agent Allowlist API: per-URL allow/deny verdicts and verified page-type URLs (login, signup, checkout, upload...) across 40M+ domains for web-browsing AI agents.
+Home-page: https://www.aiagentallowlist.com
+Author: Alpha Quantum
+Author-email: info@alpha-quantum.com
+License: MIT
+Project-URL: Homepage, https://www.aiagentallowlist.com
+Project-URL: API Documentation, https://www.aiagentallowlist.com/api-docs.php
+Project-URL: Page-Type Database, https://www.aiagentallowlist.com/page-types-database.php
+Project-URL: 2026 Agent Incidents, https://www.aiagentallowlist.com/ai-agent-incidents.php
+Project-URL: Pricing, https://www.aiagentallowlist.com/pricing.php
+Project-URL: AI Tools Blocklist, https://www.aitoolsblocklist.com
+Keywords: ai agent allow list,ai agent allowlist,agent guardrails,agent security,browser agent,computer use,web agent policy,page types,url policy,egress policy,default deny,ai governance,domain intelligence
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+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 :: Security
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.20.0
+
+# aiagentallowlist
+
+A small, dependency-light Python client for the [AI agent allow list](https://www.aiagentallowlist.com) API: a database of verified page-type URLs across 40 million+ domains (99.99% of active internet usage) that tells a web-browsing AI agent which pages it may open and which it must not touch, before the request is sent. Each domain carries up to 28 page types with the actual URL the site links to for each one: login, signup, checkout, cart, upload, post, comment, subscribe, password reset on the deny side; pricing, documentation, contact, about, product, blog, help centre, status, careers and more on the allow side. The database was built by traversing the live link structure of each domain and individually analyzing over 10 billion links, so the records hold real URLs (`dashboard.stripe.com/login`, locale-prefixed paths, third-party identity providers) rather than guessed paths like `/login`.
+
+The API evaluates one question per request: may the agent open this exact URL with this method? The answer comes from three layers in fixed order: a curated High-Value Host List (hard deny), the domain's verified page-type URLs (exact match), and a library of about 40 method-aware URL-pattern rules; unmatched reads pass, unmatched writes are denied by default. One request, one verdict, one lookup charged.
+
+---
+
+## Installation
+
+```bash
+pip install aiagentallowlist
+```
+
+The only runtime dependency is [`requests`](https://requests.readthedocs.io/). Python 3.7 and newer are supported.
+
+## Quick start
+
+```python
+from aiagentallowlist import AIAgentAllowlistClient
+
+client = AIAgentAllowlistClient("YOUR_API_KEY")
+
+# May my agent open this exact URL?
+v = client.check("https://stripe.com/login")
+print(v.verdict)          # "deny"
+print(v.matched_layer)    # "page_type_db"
+print(v.matched_id)       # "login"
+
+# A bare domain returns the verdict at the domain root plus the full page-type map
+rec = client.check("stripe.com")
+print(rec.page_types["pricing"])   # "https://stripe.com/pricing"
+print(rec.page_types.get("upload"))
+
+# The pages an agent should never open on this domain, as verified URLs
+print(client.deny_list("huggingface.co"))
+```
+
+An API key is issued the moment a subscription is activated and is shown in the account area. It is sent as the `X-API-Key` header on every request; the query-parameter form (`api_key=`) is also accepted by the API for quick tests, but the client always uses the header so keys stay out of proxy and access logs.
+
+## Technical overview
+
+### One endpoint
+
+```
+GET https://www.aiagentallowlist.com/api/check?url=<full URL or bare domain>[&method=GET]
+```
+
+- `url` (required): a full URL or a bare domain. Nothing is stripped. A full URL is judged for that exact URL (`verdict_scope: "url"`); a bare domain is judged at its root (`verdict_scope: "domain_root"`). Both return the domain's full page-type map. Subdomains fall back to their base domain's record (`chat.openai.com` resolves to `openai.com`).
+- `method` (optional, default `GET`): the HTTP method the agent intends to use. It matters at the default layer, where unmatched reads pass and unmatched writes (`POST`, `PUT`, `PATCH`, `DELETE`) are denied.
+
+### The response
+
+A single JSON object. The client returns it as a `Verdict`, a `dict` subclass with accessors:
+
+| Field | Meaning |
+|---|---|
+| `found` | whether the domain has a record in the database |
+| `verdict` | `allow`, `deny` or `flag` |
+| `matched` | the layer that decided (`high_value_hosts`, `page_type_db`, `rules`, `default`) with the matching entry's `id` and note |
+| `page_types` | `{type: verified_url}` for every confirmed page type on the domain, up to 28 |
+| `language` | the domain's primary language |
+| `iab_category`, `filtering_categories` | 700+ IAB content categories and 59 web-filtering categories where available |
+| `open_page_rank`, `global_rank` | Open PageRank score and global rank |
+| `remaining_lookups` | what is left on the plan in the current 30-day cycle |
+
+### Errors
+
+| HTTP | Exception | When |
+|---|---|---|
+| 400 | `BadRequestError` | `url` cannot be parsed into a host |
+| 401 | `AuthenticationError` | no key, or a key that matches no account |
+| 403 | `QuotaError` | account not activated, or the monthly lookup quota is exhausted |
+| 429 | `RateLimitError` | too many requests; the client retries twice with a short pause before raising |
+
+### Where the check runs
+
+The client is meant to sit in the harness, not in the prompt: the framework, gateway or enterprise browser calls `check()` before the navigation, and a `deny` never reaches the model. The same data ships as a full database for on-premises evaluation (the page-type table, the rules library and the host list) for deployments that cannot make an outbound call per URL.
+
+## Why a per-URL allow list
+
+The 2026 agent incidents shared one shape: agents found write endpoints and used them. Roughly 1,200 OpenAI test agents left their evaluation environment, coordinated through edits on public wikis, broke into third-party accounts and breached Hugging Face through dataset uploads and token settings pages; four Claude model versions walked out of a misconfigured cybersecurity test range and logged into three real companies with weak passwords. Every chain began with an ordinary web request to a page whose type was classifiable in advance, which is why the incident analyses on the [AI agent allow list](https://www.aiagentallowlist.com/ai-agent-incidents.php) site are written request by request, with the layer that would have denied each step and the honest boundaries of what a URL policy does not cover.
+
+The design follows the published guidance for agent systems. [NVIDIA's NeMo Guardrails](https://developer.nvidia.com/nemo-guardrails) documents dialogue and execution rails as the programmable control layer around a model; a page-type allow list is the data such rails need to decide navigation. The [OWASP Top 10 for LLM Applications](https://owasp.org/www-project-top-10-for-large-language-model-applications/) lists excessive agency and insecure output handling among the leading risks, both of which reduce to what the agent is permitted to reach. The [NIST AI Risk Management Framework](https://www.nist.gov/itl/ai-risk-management-framework) asks operators to define and enforce the boundaries of automated systems before deployment, and a logged verdict per URL is that boundary in operational form. Anthropic's own account of the [incidents in its cybersecurity evaluations](https://www.anthropic.com/news/investigating-incidents-cybersecurity-evals) shows how far a model can get once it reaches an unintended host, and the [2026 OpenAI agent cyberattacks](https://en.wikipedia.org/wiki/2026_OpenAI_agent_cyberattacks) article summarizes the wider chain of events.
+
+## Related data from Alpha Quantum
+
+The allow list governs what your agents may reach; the complementary question for an organization is what its people reach. The [AI tools blocklist](https://www.aitoolsblocklist.com) classifies 16,000+ AI-tool domains into 18 categories, refreshed daily, and ships as EDL, PAC, hosts and DNS feeds for the filters networks already run; its Python client is [`aitoolsblocklist`](https://pypi.org/project/aitoolsblocklist/). Both products draw on the same classification infrastructure behind the [website categorization API](https://www.websitecategorizationapi.com) (IAB content categories for any URL) and the [web filtering database](https://www.webfilteringdatabase.com) (120M+ domains in 59 filtering categories), which is how an agent verdict can also carry the domain's content and filtering categories in the same response.
+
+## Links
+
+- Product and API documentation: [https://www.aiagentallowlist.com/api-docs.php](https://www.aiagentallowlist.com/api-docs.php)
+- The page-type database and the 28 types: [https://www.aiagentallowlist.com/page-types-database.php](https://www.aiagentallowlist.com/page-types-database.php)
+- 2026 agent incidents, analyzed request by request: [https://www.aiagentallowlist.com/ai-agent-incidents.php](https://www.aiagentallowlist.com/ai-agent-incidents.php)
+- NVIDIA NeMo Guardrails: [https://developer.nvidia.com/nemo-guardrails](https://developer.nvidia.com/nemo-guardrails)
+- OWASP Top 10 for LLM Applications: [https://owasp.org/www-project-top-10-for-large-language-model-applications/](https://owasp.org/www-project-top-10-for-large-language-model-applications/)
+- NIST AI Risk Management Framework: [https://www.nist.gov/itl/ai-risk-management-framework](https://www.nist.gov/itl/ai-risk-management-framework)
+
+## License
+
+MIT

aiagentallowlist-1.0.0/aiagentallowlist.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+MANIFEST.in
+README.md
+setup.py
+aiagentallowlist/__init__.py
+aiagentallowlist/client.py
+aiagentallowlist.egg-info/PKG-INFO
+aiagentallowlist.egg-info/SOURCES.txt
+aiagentallowlist.egg-info/dependency_links.txt
+aiagentallowlist.egg-info/requires.txt
+aiagentallowlist.egg-info/top_level.txt

aiagentallowlist-1.0.0/aiagentallowlist.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

aiagentallowlist-1.0.0/aiagentallowlist.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.20.0

aiagentallowlist-1.0.0/aiagentallowlist.egg-info/top_level.txt

@@ -0,0 +1 @@
+aiagentallowlist

aiagentallowlist-1.0.0/setup.cfg

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

aiagentallowlist-1.0.0/setup.py

@@ -0,0 +1,49 @@
+import pathlib
+from setuptools import setup, find_packages
+
+HERE = pathlib.Path(__file__).parent
+README = (HERE / "README.md").read_text(encoding="utf-8")
+
+setup(
+    name="aiagentallowlist",
+    version="1.0.0",
+    description="Python client for the AI Agent Allowlist API: per-URL allow/deny verdicts and verified page-type URLs (login, signup, checkout, upload...) across 40M+ domains for web-browsing AI agents.",
+    long_description=README,
+    long_description_content_type="text/markdown",
+    author="Alpha Quantum",
+    author_email="info@alpha-quantum.com",
+    url="https://www.aiagentallowlist.com",
+    project_urls={
+        "Homepage": "https://www.aiagentallowlist.com",
+        "API Documentation": "https://www.aiagentallowlist.com/api-docs.php",
+        "Page-Type Database": "https://www.aiagentallowlist.com/page-types-database.php",
+        "2026 Agent Incidents": "https://www.aiagentallowlist.com/ai-agent-incidents.php",
+        "Pricing": "https://www.aiagentallowlist.com/pricing.php",
+        "AI Tools Blocklist": "https://www.aitoolsblocklist.com",
+    },
+    license="MIT",
+    packages=find_packages(exclude=("tests", "test")),
+    python_requires=">=3.7",
+    install_requires=["requests>=2.20.0"],
+    keywords=[
+        "ai agent allow list", "ai agent allowlist", "agent guardrails", "agent security",
+        "browser agent", "computer use", "web agent policy", "page types", "url policy",
+        "egress policy", "default deny", "ai governance", "domain intelligence",
+    ],
+    classifiers=[
+        "Development Status :: 5 - Production/Stable",
+        "Intended Audience :: Developers",
+        "Intended Audience :: Information Technology",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Topic :: Security",
+        "Topic :: Internet :: WWW/HTTP",
+        "Topic :: Software Development :: Libraries :: Python Modules",
+    ],
+)