Metadata-Version: 2.5
Name: rsoft-trust
Version: 0.1.0
Summary: RSoft Trust SDK — on-chain trust scores, policy gates and trust-based pricing for AI agents (AgentTrust-8004 on Base).
Project-URL: Homepage, https://github.com/rsoft-latam/rsoft-trust-api
Project-URL: Documentation, https://github.com/rsoft-latam/rsoft-trust-api/tree/main/packages/rsoft-trust-py
Author: RSoft Latam
License-Expression: MIT
Keywords: ai-agents,base,erc-8004,fastapi,pricing,reputation,trust,x402
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.25
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: fastapi>=0.100; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100; extra == 'fastapi'
Description-Content-Type: text/markdown

# rsoft-trust (Python)

> On-chain trust scores, policy gates and trust-based pricing for AI agents —
> the [RSoft Trust](../../README.md) API (AgentTrust-8004 on Base mainnet) as an
> async SDK on httpx. Python 3.10+.

```bash
pip install rsoft-trust            # not published yet — build from source, see below
pip install "rsoft-trust[fastapi]" # + the FastAPI dependency
```

```python
from rsoft_trust import TrustClient

async with TrustClient() as trust:                # public deployment by default
    r = await trust.evaluate("0xB684…2B13", policy="financial", include_pricing=True, base_price_usdc=0.10)

r["trust_score"]     # 24
r["trust_tier"]      # "untrusted" | "limited" | "verified" | "trusted" | "blocked"
r["all_passed"]      # False
r["gate_results"]    # [{"gate": "established", "passed": False, "value": 4.06, "threshold": 30}, …]
r["pricing"]["price_multiplier"]   # 1.64 → suggested_price_usdc 0.164
```

`await trust.require(wallet, "strict")` is `evaluate()` that raises
`TrustGateError` (with `.failed_gates` and `.to_dict()`) when the policy fails.

## What the score is made of (and what it is not)

Every gate is derived from signals the API reads **on-chain, today**:
ERC-8004 identity (`registered`), identity age (`established`), reputation
clients (`active`), census coherence (`coherent`) and the 0–100 `score`.
There is no KYC, sanctions or off-chain gate — the model does not have one.
Full gate/tier/pricing tables: [API README](../../README.md#policy-evaluation--post-evaluate).

## Policies

```python
await trust.evaluate(wallet, "quick")        # registered
await trust.evaluate(wallet, "basic")        # + coherent
await trust.evaluate(wallet, "standard")     # + score ≥ 40   (default)
await trust.evaluate(wallet, "strict")       # + 90 d, 5 clients, score ≥ 75
await trust.evaluate(wallet, "financial")    # + 30 d, 3 clients, score ≥ 50
await trust.evaluate(wallet, "reputation")   # weighted vote ≥ 0.60

await trust.evaluate(wallet, {"gates": ["registered", {"gate": "score", "threshold": 60}], "operator": "AND"})
```

## FastAPI dependency — `rsoft_trust.fastapi.require_trust`

```python
from fastapi import Depends, FastAPI
from rsoft_trust.fastapi import require_trust

app = FastAPI()

@app.get("/paid", dependencies=[Depends(require_trust(policy="financial"))])
async def paid():
    ...

@app.get("/tier")
async def tier(verdict: dict = Depends(require_trust("standard"))):
    return {"tier": verdict["trust_tier"]}       # also on request.state.trust
```

Wallet comes from the `X-Wallet` header, then `?wallet=` (override with
`wallet_from=lambda request: ...`). No wallet → 401 · malformed → 400 ·
policy failed → **403** with `detail = {error, trust_score, trust_tier,
failed_gates, gate_results}` and an `X-Trust-Tier` header · Trust API
unreachable → 502 (never fail-open on a real verdict).

## Pricing

`include_pricing=True` (or `await trust.pricing(wallet, base_price_usdc)`) returns:

- `price_multiplier` ∈ [0.5, 2.0] — `2.0 − 1.5·score/100`; anomaly or unregistered → 2.0.
- `suggested_interest_rate` — indicative annual rate on the RSoft Bank's own
  scale (its formula in the zero-exposure limit); `None` for CCC/D. The Bank
  quotes its own rate; this is a hint, not a quote.

## Client options

```python
TrustClient(
    base_url=DEFAULT_BASE_URL,   # public RSoft Trust deployment
    api_key=None,                # sent as X-API-Key; reserved — the public API is unauthenticated today
    timeout=45.0,                # cold on-chain reads take ~10–30 s
    transport=None,              # httpx transport (tests)
    client=None,                 # bring your own httpx.AsyncClient
)
```

Errors: `TrustApiError` (`.status`, `.body`; status 0 for transport errors),
`TrustGateError` from `require()`, `ValueError` for a malformed wallet
(checked before any request).

## Build from source

```bash
cd packages/rsoft-trust-py
pip install -e ".[dev]" && python -m pytest -q
python -m build            # → dist/rsoft_trust-0.1.0-py3-none-any.whl + .tar.gz
```
