Metadata-Version: 2.4
Name: synapsai
Version: 0.4.0
Summary: Official Python SDK for the SynapsAI Truth-as-a-Service API
Project-URL: Homepage, https://synapsai.org/docs
Project-URL: Repository, https://github.com/SynapsAINetwork/SynapsAI-Dev
Author-email: SynapsAI <jonathan@synapsai.org>
License: MIT
Keywords: ai-verification,blockchain,synapsai,taas,trust,verification
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: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.22.0; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Description-Content-Type: text/markdown

# synapsai

Official Python SDK for the [SynapsAI](https://synapsai.org) Truth-as-a-Service (TaaS) API.

## Install

```bash
pip install synapsai
```

Requires **Python 3.9+**. Runtime dependency: `httpx` only.

## Quickstart

```python
from synapsai import SynapsAI

client = SynapsAI(api_key="taas_your_key")
# or set SYNAPSAI_API_KEY env var and call SynapsAI() with no arguments
```

Get your API key at [synapsai.org/api-access](https://synapsai.org/api-access).

---

## Verification

### Image verification

Detects AI-generated images, deepfakes, and edits using Hive AI, ELA, EXIF, and Claude Vision. Result committed on-chain.

```python
from pathlib import Path
from synapsai import SynapsAI

client = SynapsAI(api_key="taas_your_key")

result = client.verify.image(
    image=Path("photo.jpg"),
    claim="Product photo from supplier",
)

print(result.verdict)            # 'AUTHENTIC'
print(result.authenticity_score) # 91  (0-100 integer)
print(result.raw_scores.hive_ai_generated)  # 0.02
print(result.tx_hash)            # on-chain proof
```

`raw_scores` exposes every signal so you can apply your own thresholds:

```python
# Insurance (conservative)
if result.raw_scores.hive_ai_generated > 0.99:
    flag_for_review()

# News (liberal)
if result.raw_scores.hive_ai_generated > 0.70:
    flag_for_review()
```

### Claim verification (text)

```python
# Submit (returns immediately — verification is async)
claim = client.verify.claim("Company X reduced CO2 by 500 tons in 2025.")
print(claim.claim_id)  # 94
print(claim.poll)      # '/v1/verify/94'

# Poll until verified
import time

def wait_for_verification(claim_id, max_wait=60):
    start = time.time()
    while time.time() - start < max_wait:
        status = client.verify.get(claim_id)
        if status.status != "pending":
            return status
        time.sleep(3)
    raise TimeoutError("Verification timed out")

status = wait_for_verification(claim.claim_id)
print(status.verified)  # True
```

### Document verification

```python
result = client.verify.document(document=Path("claim.pdf"))
print(result.verdict)
print(result.checks)                     # [DocumentCheck(name=..., passed=..., detail=...)]
print(result.ai_detection.is_ai_generated)  # False
```

### Luxury goods authentication

```python
result = client.verify.luxury(
    images=[Path("front.jpg"), Path("serial.jpg")],
    brand="Rolex",
    model="Submariner",
)

print(result.verdict)     # 'AUTHENTIC'
print(result.confidence)  # 92
print(result.indicators)  # VisualAuthIndicators(authentic=[...], suspicious=[])
```

### Other visual authentication endpoints

All accept `image: Path | bytes | BinaryIO` or a list of those.

```python
client.verify.rx(images=img, drug_name="Advil")
client.verify.credential(images=img, credential_type="degree")
client.verify.art(images=img, artist="Monet")
client.verify.sneakers(images=img, brand="Nike")
client.verify.cards(images=img, card_type="Pokemon")
client.verify.wine(images=img, producer="Château Pétrus")
client.verify.ticket(images=img, event="Super Bowl LX")
client.verify.jewelry(images=img, metal="gold")
client.verify.electronics(images=img, brand="Apple")
```

---

## Trust Scores

```python
trust = client.trust.get("0xWalletAddress")
print(trust.trust_score)      # 590  (neutral=500, range 0-1000)
print(trust.interpretation)   # 'trusted'

# Batch
scores = client.trust.batch(["0xAddr1", "0xAddr2"])
```

---

## Webhooks

```python
# Register
wh = client.webhooks.create(
    url="https://your-server.com/hooks/synapsai",
    events=["verification.completed"],
)
# Store wh.secret securely — shown once
print(wh.id)      # 'wh_abc123'
print(wh.secret)  # 'whsec_...'

# Verify incoming events (Flask example)
import os
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/hooks/synapsai")
def handle_webhook():
    valid = client.webhooks.verify_signature(
        payload=request.get_data(),        # raw bytes — do NOT parse first
        signature=request.headers["X-SynapsAI-Signature"],
        secret=os.environ["SYNAPSAI_WEBHOOK_SECRET"],
    )
    if not valid:
        abort(401)
    event = request.get_json()
    # handle event...
    return "", 200

# List / manage
webhooks = client.webhooks.list()
client.webhooks.test("wh_abc123")
client.webhooks.delete("wh_abc123")
```

---

## Account

```python
info = client.account.key_info()
print(info.plan)     # 'growth'
print(info.company)  # 'Acme Insurance'

usage = client.account.usage()
print(usage.total_calls)  # 42

from datetime import datetime, timezone

page = client.account.history(
    type="image",
    limit=50,
    from_=datetime(2026, 5, 1, tzinfo=timezone.utc),
)
print(page.total)
print(page.verifications[0].verdict)
```

---

## Async client

```python
import asyncio
from synapsai import AsyncSynapsAI

async def main():
    async with AsyncSynapsAI(api_key="taas_your_key") as client:
        result = await client.verify.image(image=Path("photo.jpg"))
        print(result.verdict)

asyncio.run(main())
```

---

## Error handling

```python
from synapsai import (
    SynapsAIError,
    AuthError,
    RateLimitError,
    ValidationError,
    NotFoundError,
    ServerError,
)

try:
    result = client.verify.image(image=Path("photo.jpg"))
except AuthError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after_ms}ms")
except ValidationError as e:
    print(f"Bad input: {e.message}")
except ServerError:
    print("Server error — retries exhausted")
```

5xx errors are retried automatically up to `max_retries` times (default 3) with exponential backoff. Set `max_retries=0` to disable.

---

## Environment variable

```bash
export SYNAPSAI_API_KEY=taas_your_key
```

```python
client = SynapsAI()  # picks up SYNAPSAI_API_KEY automatically
```

---

## Configuration

```python
client = SynapsAI(
    api_key="taas_...",          # or SYNAPSAI_API_KEY env var
    base_url="https://api.synapsai.org",  # optional override
    max_retries=3,               # default 3
    timeout=30.0,                # seconds, default 30
)
```
