synapsai 0.1.0__tar.gz

synapsai-0.1.0/.gitignore

@@ -0,0 +1,53 @@
+# Dependencies
+node_modules/
+
+# Build output
+.next/
+out/
+
+# Environment files (contain private keys)
+.env
+.env.local
+.env.production
+.env.development
+taas-api/.env
+node-client/.env
+
+# TaaS runtime data (contains real API keys — never commit)
+taas-api/data/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Backup/duplicate files
+*.bak
+*.backup*
+*.original
+*.patch
+*.save
+*.full
+
+# macOS duplicate files (Finder copies)
+*\ 2.*
+*\ 3.*
+*\ 2/
+*\ 3/
+
+# Hardhat
+contracts/artifacts/
+contracts/cache/
+contracts/node_modules/
+
+# Logs
+node-client/logs/
+
+# PM2
+.pm2/
+
+# IDE
+.vscode/
+.idea/
+
+# Next.js
+next-env.d.ts

synapsai-0.1.0/PKG-INFO

@@ -0,0 +1,292 @@
+Metadata-Version: 2.4
+Name: synapsai
+Version: 0.1.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
+)
+```

synapsai-0.1.0/README.md

@@ -0,0 +1,266 @@
+# 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
+)
+```

synapsai-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "synapsai"
+version = "0.1.0"
+description = "Official Python SDK for the SynapsAI Truth-as-a-Service API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "SynapsAI", email = "jonathan@synapsai.org" }]
+keywords = ["synapsai", "verification", "trust", "blockchain", "taas", "ai-verification"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.24.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4",
+    "pytest-httpx>=0.22.0",
+    "pytest-asyncio>=0.21.0",
+]
+
+[project.urls]
+Homepage = "https://synapsai.org/docs"
+Repository = "https://github.com/SynapsAINetwork/SynapsAI-Dev"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/synapsai"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"