Metadata-Version: 2.4
Name: entropy0
Version: 0.1.3
Summary: Entropy0 Python SDK — pre-ingestion source trust for AI agents
Project-URL: Homepage, https://entropy0.ai
Project-URL: Documentation, https://entropy0.ai/docs
Project-URL: Repository, https://github.com/entropy0dev/sdk
Project-URL: Issues, https://github.com/entropy0dev/sdk/issues
Author-email: Entropy0 <dev@entropy0.ai>
License: MIT
Keywords: ai-agents,domain-intelligence,guardrail,llm,pre-ingestion,rag,source-trust,trust
Classifier: Development Status :: 4 - Beta
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 :: Internet :: WWW/HTTP
Classifier: Topic :: Security
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24.0
Description-Content-Type: text/markdown

# entropy0

Python SDK for [Entropy0](https://entropy0.ai) — pre-ingestion source trust for AI agents.

```bash
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

```python
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](https://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.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

```python
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

```python
from entropy0 import AsyncEntropy0Client

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

### Batch

```python
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.

```python
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:

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

## LangChain example

```python
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

```python
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](https://entropy0.ai/docs)
- [Decision model](https://entropy0.ai/docs/decision-model)
- [Get an API key](https://entropy0.ai/signup)
- [OpenAPI spec](https://entropy0.ai/openapi.json)
