Metadata-Version: 2.4
Name: djd-agent-score
Version: 0.1.0
Summary: Python SDK for DJD Agent Score — reputation scoring for AI agent wallets on Base L2
Project-URL: Homepage, https://djdagentscore.dev
Project-URL: Documentation, https://djdagentscore.dev/docs
Project-URL: Repository, https://github.com/jacobsd32-cpu/djd-agent-score-python
Project-URL: Issues, https://github.com/jacobsd32-cpu/djd-agent-score-python/issues
Author-email: Drew Jacobs <feedback@djdagentscore.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,base-l2,blockchain,reputation,scoring,trust,x402
Classifier: Development Status :: 3 - Alpha
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.25.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1.0; extra == 'langchain'
Description-Content-Type: text/markdown

# DJD Agent Score — Python SDK

Python SDK for [DJD Agent Score](https://djdagentscore.dev) — reputation scoring for AI agent wallets on Base L2.

## Installation

```bash
pip install djd-agent-score
```

With LangChain support:

```bash
pip install djd-agent-score[langchain]
```

## Quick Start

```python
from djd_agent_score import AgentScoreClient

client = AgentScoreClient()
score = client.get_score("0x1234...abcd")

print(f"{score.wallet}: {score.score}/100 ({score.tier})")
```

## Usage

### Free Endpoints

```python
from djd_agent_score import AgentScoreClient

client = AgentScoreClient()

# Basic score (10 free lookups/day per IP)
score = client.get_score("0x...")
print(score.score, score.tier, score.confidence)

# Leaderboard
lb = client.get_leaderboard()
for entry in lb.leaderboard[:5]:
    print(f"#{entry.rank} {entry.wallet} — {entry.score} ({entry.tier})")

# Register an agent
reg = client.register_agent(
    "0x...",
    name="MyAgent",
    description="Autonomous trading agent",
    github_url="https://github.com/user/repo",
)
```

### Paid Endpoints (API Key Required)

```python
client = AgentScoreClient(api_key="djd_live_...")

# Full dimensional breakdown ($0.10)
full = client.get_full_score("0x...")
print(full.dimensions.reliability.score)
print(full.sybil_flag, full.gaming_indicators)
print(full.trajectory)

# Score history with trend analysis ($0.15)
history = client.get_score_history("0x...", limit=20)
print(history.trend, history.trajectory)

# Batch scoring ($0.50 flat for 2-20 wallets)
batch = client.get_batch_scores(["0x...", "0x...", "0x..."])
for result in batch.results:
    print(f"{result.wallet}: {result.score}")

# Force fresh recalculation ($0.25)
fresh = client.refresh_score("0x...")
```

### Async Client

```python
import asyncio
from djd_agent_score import AsyncAgentScoreClient

async def main():
    async with AsyncAgentScoreClient(api_key="djd_live_...") as client:
        score = await client.get_score("0x...")
        print(score.tier)

asyncio.run(main())
```

### Error Handling

```python
from djd_agent_score import AgentScoreClient
from djd_agent_score.exceptions import RateLimitError, ValidationError, NotFoundError

client = AgentScoreClient()
try:
    score = client.get_score("0xinvalid")
except ValidationError as e:
    print(f"Bad request: {e}")
except RateLimitError as e:
    print(f"Rate limited: {e}")
except NotFoundError as e:
    print(f"Not found: {e}")
```

### LangChain Integration

```python
from djd_agent_score.langchain import AgentScoreToolkit

toolkit = AgentScoreToolkit(api_key="djd_live_...")
tools = toolkit.get_tools()

# Use with any LangChain agent
from langchain.agents import initialize_agent
agent = initialize_agent(tools, llm, agent="zero-shot-react-description")
agent.run("Is wallet 0x... trustworthy? Check its agent score.")
```

## API Reference

| Method | Endpoint | Price | Description |
|--------|----------|-------|-------------|
| `get_score(wallet)` | GET /v1/score/basic | Free (10/day) | Basic score + tier |
| `get_full_score(wallet)` | GET /v1/score/full | $0.10 | Full dimensional breakdown |
| `refresh_score(wallet)` | POST /v1/score/refresh | $0.25 | Force live recalculation |
| `get_score_history(wallet)` | GET /v1/score/history | $0.15 | Historical scores + trend |
| `get_batch_scores(wallets)` | POST /v1/score/batch | $0.50 | 2-20 wallets at once |
| `get_leaderboard()` | GET /v1/leaderboard | Free | Top-ranked agents |
| `register_agent(wallet, ...)` | POST /v1/agent/register | Free | Register on the network |
| `report_fraud(target, ...)` | POST /v1/report | $0.02 | Submit fraud report |

## Environment Variables

| Variable | Description |
|----------|-------------|
| `DJD_AGENT_SCORE_API_KEY` | API key for paid endpoints |
| `DJD_AGENT_SCORE_BASE_URL` | Custom API base URL (default: `https://djdagentscore.dev`) |

## Links

- [API Documentation](https://djdagentscore.dev/docs)
- [OpenAPI Spec](https://djdagentscore.dev/openapi.json)
- [MCP Server](https://www.npmjs.com/package/djd-agent-score-mcp) — for Claude, GPT, and other LLM agents
- [TypeScript SDK](https://www.npmjs.com/package/djd-agent-score-client)

## License

MIT — see [LICENSE](LICENSE).
