entropy0

Python SDK for Entropy0 — pre-ingestion source trust for AI agents.

pip install entropy0

What it does

Entropy0 evaluates source-level infrastructure signals before an agent fetches an external URL. One call before requests.get() or httpx.get() returns whether the source is allowed to fetch under your selected policy.

Quick start

import os
from entropy0 import Entropy0Client

client = Entropy0Client()  # reads ENTROPY0_API_KEY from env

result = client.decide("github.com")
print(result.action)          # "proceed"
print(result.scores.trust)    # 96
print(result.should_fetch)    # True

result = client.decide("githvb.com")
print(result.action)          # "deny"
print(result.reason_codes)    # ["BRAND_MISMATCH", "NEWLY_REGISTERED_DOMAIN"]
print(result.should_fetch)    # False

Get an API key at entropy0.ai/signup. The Developer plan is free.

Actions

result.should_fetch is True for proceed and proceed_with_caution. result.is_allowed and result.is_safe are aliases for the same check.

should_fetch / is_allowed / is_safe reflect whether the recommended action allows automated fetch under the selected policy. They are not a guarantee that the source or page content is safe.

Usage

Sync client

from entropy0 import Entropy0Client

with Entropy0Client(api_key="sk_ent0_...") as client:
    result = client.decide("example.com")
    if result.should_fetch:
        # fetch the URL
        ...
    else:
        print(f"Blocked ({result.action}): {result.reason_codes}")

Async client

from entropy0 import AsyncEntropy0Client

async with AsyncEntropy0Client() as client:
    result = await client.decide("example.com")

Batch

results = client.batch(["github.com", "githvb.com", "pypi.org"])
for r in results:
    print(r.target_value, r.action, r.scores.trust)

URL evaluation (Team+ plans)

decide_url passes the full URL path to the API. On Developer/free plans it automatically falls back to domain evaluation.

result = client.decide_url("https://github.com/user/repo/raw/main/script.sh")

Interaction context

The defaults (fetch / read_only / medium / balanced) are suitable for most RAG pipelines. Override when needed:

result = client.decide(
    "example.com",
    interaction_kind="api_call",
    interaction_mode="read_write",
    interaction_sensitivity="high",
    policy_profile="strict",
)

LangChain example

from langchain_core.tools import tool
from entropy0 import Entropy0Client, SAFE_ACTIONS

_client = Entropy0Client()

@tool
def entropy0_decide(url: str) -> str:
    """
    Call this before fetching, reading, summarizing, citing, or acting on
    any external URL or domain. If the returned action is not 'proceed' or
    'proceed_with_caution', do NOT call fetch_url — report the action and
    reason_codes to the user instead.
    """
    result = _client.decide(url)
    return (
        f"action={result.action} trust={result.scores.trust} "
        f"threat={result.scores.threat} reason_codes={result.reason_codes}"
    )

Error handling

from entropy0 import Entropy0Client, AuthenticationError, RateLimitError, APIError

try:
    result = client.decide("example.com")
except AuthenticationError:
    # bad or missing API key
    ...
except RateLimitError as e:
    # e.retry_after is seconds until reset (if provided by the API)
    ...
except APIError as e:
    # e.status_code for the HTTP status
    ...

Links

• API docs
• Decision model
• Get an API key
• OpenAPI spec