entropy0 0.1.0

Entropy0 Python SDK — source trust and URL safety for AI agents

entropy0

Python SDK for Entropy0 — source trust and URL safety 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() tells you whether the source is safe to interact with.

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.is_safe)         # True

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

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

Actions

Action	Meaning
proceed	Source infrastructure posture is consistent with normal automated interaction
proceed_with_caution	Acceptable; keep interaction read-only
sandbox	Elevated signals; interact only in a constrained environment
escalate_to_human	Ambiguous or high-risk; request human review
deny	Infrastructure posture is inconsistent with safe automated interaction

result.is_safe is True for proceed and proceed_with_caution.

Usage

Sync client

from entropy0 import Entropy0Client

with Entropy0Client(api_key="sk_ent0_...") as client:
    result = client.decide("example.com")
    if result.is_safe:
        # 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