Metadata-Version: 2.4
Name: agentscore
Version: 0.1.0
Summary: Python SDK for DJD Agent Score — trust scoring for AI agent wallets on Base
Project-URL: Homepage, https://djd-agent-score.fly.dev
Project-URL: Documentation, https://djd-agent-score.fly.dev/docs
Project-URL: Repository, https://github.com/djd-agent-score/agentscore-python
Author-email: DJD <drew@djd.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,base,blockchain,reputation,trust,x402
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24
Provides-Extra: all
Requires-Dist: crewai-tools>=0.14; extra == 'all'
Requires-Dist: crewai>=0.80; extra == 'all'
Requires-Dist: langchain-core>=0.2; extra == 'all'
Provides-Extra: crewai
Requires-Dist: crewai-tools>=0.14; extra == 'crewai'
Requires-Dist: crewai>=0.80; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2; extra == 'langchain'
Description-Content-Type: text/markdown

# agentscore

Python SDK for the [DJD Agent Score API](https://djd-agent-score.fly.dev) — trust scoring for AI agent wallets on Base.

[![Listed in the Coinbase x402 Ecosystem](https://img.shields.io/badge/Coinbase_x402-Ecosystem-0052FF?style=flat&logo=coinbase)](https://github.com/coinbase/x402)
[![PyPI version](https://img.shields.io/pypi/v/agentscore)](https://pypi.org/project/agentscore/)

## Install

```bash
pip install agentscore
```

### With framework integrations

```bash
pip install agentscore[langchain]   # LangChain tools
pip install agentscore[crewai]      # CrewAI tools
pip install agentscore[all]         # Everything
```

## Quick Start

```python
from agentscore import AgentScoreClient

client = AgentScoreClient()
result = client.basic_score("0xABC...")

print(result.score)           # 72
print(result.tier)            # "Trusted"
print(result.recommendation)  # "proceed"
```

### Async

```python
from agentscore import AsyncAgentScoreClient

async with AsyncAgentScoreClient() as client:
    result = await client.basic_score("0xABC...")
```

### Trust Gate Decorator

Guard any function with a trust check:

```python
from agentscore import trust_gate

@trust_gate(min_score=50)
def send_payment(wallet: str, amount: float):
    # Only runs if wallet scores >= 50
    ...
```

### LangChain

```python
from agentscore.langchain import AgentScoreTool, TrustGatedTool

# Add trust checking as a tool
tools = [AgentScoreTool(), ...other_tools]

# Wrap an existing tool with trust gating
safe_transfer = TrustGatedTool(
    tool=transfer_tool,
    min_score=50,
    wallet_param="recipient",
)
```

### CrewAI

```python
from agentscore.crewai import check_agent_trust

agent = Agent(
    role="Transaction Validator",
    tools=[check_agent_trust],
)
```

## API Methods

| Method | Description | Tier |
|--------|-------------|------|
| `basic_score(wallet)` | Basic reputation score | Free |
| `full_score(wallet)` | Full score with dimensions | Paid (x402) |
| `refresh_score(wallet)` | Force refresh from chain | Paid (x402) |
| `should_transact(wallet)` | Quick yes/no check | Free |
| `gate_transaction(wallet)` | Full gating decision | Free |
| `report_fraud(wallet, reason)` | Submit fraud report | Free |
| `check_blacklist(wallet)` | Check fraud reports | Paid (x402) |
| `get_badge(wallet)` | SVG trust badge | Free |
| `get_leaderboard(limit)` | Top scored agents | Free |
| `register_agent(wallet, ...)` | Register agent wallet | Free |
| `health_check()` | API health status | Free |

## Error Handling

```python
from agentscore import PaymentRequiredError, NetworkError

try:
    result = client.full_score("0xABC...")
except PaymentRequiredError as e:
    print(f"Payment needed: {e.accepts[0].max_amount_required} {e.accepts[0].asset}")
    print(f"Pay to: {e.accepts[0].pay_to}")
except NetworkError as e:
    print(f"API error: {e} (status: {e.status_code})")
```

## License

MIT
