attesto 0.1.2__tar.gz

attesto-0.1.2/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: attesto
+Version: 0.1.2
+Summary: Attesto AI Python SDK — log verifiable AI events to Polygon via one function call.
+Author-email: Attesto <info@attesto.eu>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://attesto.eu
+Project-URL: Documentation, https://docs.attesto.eu/manuals/sdks.html
+Project-URL: Security, https://attesto.eu/security
+Keywords: ai,compliance,eu-ai-act,polygon,merkle,audit
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+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
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: pytest-httpx>=0.35; extra == "dev"
+Requires-Dist: ruff>=0.7; extra == "dev"
+
+# Attesto Python SDK
+
+Log every AI decision to a verifiable, on-chain audit trail with one call.
+
+```bash
+pip install attesto
+```
+
+## Quick start
+
+```python
+from attesto import AttestoClient
+
+attesto = AttestoClient(api_key="atto_live_...")  # issued when you register a system
+ack = attesto.log_event(
+    type="inference",
+    status="verified",
+    latency_ms=42,
+    input_hash="sha256:deadbeef...",
+    output_hash="sha256:cafebabe...",
+    payload={"score": 0.87, "model": "gpt-4o"},
+)
+print(ack.id, ack.system_id, ack.ts)
+```
+
+## Async
+
+```python
+from attesto import AsyncAttestoClient
+
+async with AsyncAttestoClient(api_key="atto_live_...") as attesto:
+    ack = await attesto.log_event(type="inference", payload={"score": 0.87})
+```
+
+## Proofstream v2
+
+```python
+import os
+from attesto import AttestoV2Client
+
+with AttestoV2Client(api_key="atto_live_...") as attesto:
+    receipt_signer_public_key_hex = os.environ["ATTESTO_RECEIPT_SIGNER_PUBLIC_KEY_HEX"]
+    stream = attesto.create_stream(
+        use_case="ai-decision-history",
+        policy_id="policy-2026-01",
+    )
+    receipt = attesto.log_event(
+        stream_id=stream.stream_id,
+        source_ref="upstream-event-123",
+        event_type="decision",
+        payload={"decision": "approve", "score": 91},
+    )
+    batch = attesto.log_events(
+        stream.stream_id,
+        [
+            {"source_ref": "upstream-event-124", "payload": {"score": 88}},
+            {
+                "source_ref": "upstream-event-125",
+                "event_type": "decision",
+                "payload": {"decision": "review"},
+            },
+        ],
+    )
+    assert batch.accepted == 2
+    stored = attesto.get_receipt(receipt.stream_event_id)
+    report = attesto.verify_receipt(
+        receipt=stored.receipt,
+        public_key_hex=receipt_signer_public_key_hex,
+        stream_event_id=receipt.stream_event_id,
+    )
+    assert report.ok
+
+    consistency = attesto.get_checkpoint_consistency(
+        "chk_current",
+        from_checkpoint_id="chk_previous",
+    )
+    assert consistency.step_count >= 1
+
+    policy = attesto.get_witness_policy("policy-ai-credit-v1")
+    assert policy.policy_hash
+
+    # Bundle export is intentionally stricter than receipt ingest: every
+    # checkpoint in the selected range must already have witness quorum
+    # evidence and a confirmed anchor epoch.
+    bundle = attesto.build_verifier_bundle(
+        from_checkpoint_id="chk_previous",
+        to_checkpoint_id="chk_current",
+    )
+    assert bundle.bundle_hash
+
+    # Present only after the checkpoint has confirmed on-chain.
+    anchor = attesto.get_anchor_epoch("aep_...")
+    assert anchor.status == "confirmed"
+
+    offline = attesto.verify_object(kind="bundle", proof_object=bundle.bundle)
+    assert offline.ok
+```
+
+`AttestoV2Client` talks to the production `/v2/streams`,
+`/v2/streams/{stream_id}/events`,
+`/v2/streams/{stream_id}/events/batch`, `/v2/receipts`, `/v2/windows`,
+`/v2/checkpoints`, `/v2/checkpoints/{checkpoint_id}/consistency`,
+`/v2/witness/policies/{policy_id}`, `/v2/anchors/{anchor_epoch_id}`,
+`/v2/ivc/epochs/{ivc_epoch_id}`, `/v2/audit/packs`, and `/v2/verify`
+APIs. Single and batch writes both return signed receipts. It exposes witness
+policy and review-gated IVC epoch visibility. Receipt ingest can run before
+enforced rollout gates; verifier-bundle export requires witnessed and confirmed
+anchored checkpoints. Nova proof production remains review-gated until that
+rollout gate is enabled.
+
+## Signed webhook connectors
+
+Use the connector helper when an external source posts to a signed-webhook
+connector endpoint:
+
+```python
+import json
+from attesto import signed_connector_webhook_headers
+
+body = json.dumps({"sourceRef": "evt_123"}, separators=(",", ":")).encode()
+headers = signed_connector_webhook_headers(connector_secret, body)
+```
+
+The helper signs `timestamp + "." + raw_body_bytes` and returns the exact
+`X-Attesto-Connector-*` headers expected by
+`/v2/connectors/signed-webhooks/{connectorId}/events`.
+
+## Batching
+
+```python
+attesto.log_events([
+    {"type": "inference", "latency_ms": 40},
+    {"type": "inference", "latency_ms": 33},
+    {"type": "decision", "status": "pending", "payload": {"threshold": 0.7}},
+])
+```
+
+Up to 1000 events per batch. The Attesto worker then groups them into a
+Merkle tree and commits the root on Polygon mainnet within your tenant's
+configured cadence (6h / 1h / per-event).
+
+## Configuration
+
+| arg | default | purpose |
+|-----|---------|---------|
+| `api_key` | — | Required. Must match `atto_live_<32 lowercase hex chars>` or `atto_test_<32 lowercase hex chars>`. |
+| `base_url` | `https://verify.attesto.eu` | Public Attesto API origin. Override only for private/staging deployments. |
+| `timeout_s` | `10.0` | Per-request timeout. |
+| `max_retries` | `3` | Retries on 5xx / 429 / transport errors, with jittered exponential backoff. |
+| `user_agent` | `attesto-python/0.1.2` | Sent as the UA header. |
+
+## Error handling
+
+```python
+from attesto import (
+    AttestoClient,
+    AuthError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+try:
+    attesto.log_event(type="inference")
+except AuthError as exc:        # 401 / 403 — bad key
+    ...
+except RateLimitError as exc:   # 429 — exceeded tenant rate limit
+    ...
+except ValidationError as exc:  # 4xx payload problem
+    ...
+except ServerError as exc:      # 5xx after all retries exhausted
+    ...
+```
+
+All Attesto SDK exceptions expose `status` and `detail` when the server
+returned an HTTP response. Transport failures keep both as `None`.
+
+## What you get
+
+Every event:
+
+1. Canonicalised to byte-exact JSON (sort keys, no whitespace, ASCII-safe).
+2. SHA-256 hashed into a Merkle leaf.
+3. Batched with other events at your cadence.
+4. The Merkle root is committed on-chain via APSProvenance.
+5. Every anchored event gets a tenant-authenticated proof from
+   `GET /v1/events/{id}/proof`. The proof payload contains
+   `canonicalJson`, `proof`, and `batchId`; submit those fields to
+   `POST https://verify.attesto.eu/v1/public/verify` or paste them into
+   the `/verify` page for independent verification.
+
+You never handle keys, wallets, or gas — Attesto pays the gas and handles
+the on-chain flow.
+
+## Production behavior
+
+- Defaults to `https://verify.attesto.eu`; override `base_url` only for
+  private or staging deployments.
+- Use this SDK from server-side code only. Attesto system API keys are bearer
+  secrets and must never be embedded in browser bundles, mobile apps, logs, or
+  client-visible environment variables.
+- Validates the key shape locally before making network calls. Production
+  system keys are shown once when the system is registered in Attesto.
+- Validates `base_url` locally and accepts only `http` or `https` origins.
+- Adds an `Idempotency-Key` header automatically for single-event and batch writes.
+- Retries transient 429, 5xx, and transport failures with exponential backoff.
+- Caps batch ingestion at 1000 events per request.
+- Never handles wallets, private keys, or gas in application code.

attesto-0.1.2/README.md

@@ -0,0 +1,208 @@
+# Attesto Python SDK
+
+Log every AI decision to a verifiable, on-chain audit trail with one call.
+
+```bash
+pip install attesto
+```
+
+## Quick start
+
+```python
+from attesto import AttestoClient
+
+attesto = AttestoClient(api_key="atto_live_...")  # issued when you register a system
+ack = attesto.log_event(
+    type="inference",
+    status="verified",
+    latency_ms=42,
+    input_hash="sha256:deadbeef...",
+    output_hash="sha256:cafebabe...",
+    payload={"score": 0.87, "model": "gpt-4o"},
+)
+print(ack.id, ack.system_id, ack.ts)
+```
+
+## Async
+
+```python
+from attesto import AsyncAttestoClient
+
+async with AsyncAttestoClient(api_key="atto_live_...") as attesto:
+    ack = await attesto.log_event(type="inference", payload={"score": 0.87})
+```
+
+## Proofstream v2
+
+```python
+import os
+from attesto import AttestoV2Client
+
+with AttestoV2Client(api_key="atto_live_...") as attesto:
+    receipt_signer_public_key_hex = os.environ["ATTESTO_RECEIPT_SIGNER_PUBLIC_KEY_HEX"]
+    stream = attesto.create_stream(
+        use_case="ai-decision-history",
+        policy_id="policy-2026-01",
+    )
+    receipt = attesto.log_event(
+        stream_id=stream.stream_id,
+        source_ref="upstream-event-123",
+        event_type="decision",
+        payload={"decision": "approve", "score": 91},
+    )
+    batch = attesto.log_events(
+        stream.stream_id,
+        [
+            {"source_ref": "upstream-event-124", "payload": {"score": 88}},
+            {
+                "source_ref": "upstream-event-125",
+                "event_type": "decision",
+                "payload": {"decision": "review"},
+            },
+        ],
+    )
+    assert batch.accepted == 2
+    stored = attesto.get_receipt(receipt.stream_event_id)
+    report = attesto.verify_receipt(
+        receipt=stored.receipt,
+        public_key_hex=receipt_signer_public_key_hex,
+        stream_event_id=receipt.stream_event_id,
+    )
+    assert report.ok
+
+    consistency = attesto.get_checkpoint_consistency(
+        "chk_current",
+        from_checkpoint_id="chk_previous",
+    )
+    assert consistency.step_count >= 1
+
+    policy = attesto.get_witness_policy("policy-ai-credit-v1")
+    assert policy.policy_hash
+
+    # Bundle export is intentionally stricter than receipt ingest: every
+    # checkpoint in the selected range must already have witness quorum
+    # evidence and a confirmed anchor epoch.
+    bundle = attesto.build_verifier_bundle(
+        from_checkpoint_id="chk_previous",
+        to_checkpoint_id="chk_current",
+    )
+    assert bundle.bundle_hash
+
+    # Present only after the checkpoint has confirmed on-chain.
+    anchor = attesto.get_anchor_epoch("aep_...")
+    assert anchor.status == "confirmed"
+
+    offline = attesto.verify_object(kind="bundle", proof_object=bundle.bundle)
+    assert offline.ok
+```
+
+`AttestoV2Client` talks to the production `/v2/streams`,
+`/v2/streams/{stream_id}/events`,
+`/v2/streams/{stream_id}/events/batch`, `/v2/receipts`, `/v2/windows`,
+`/v2/checkpoints`, `/v2/checkpoints/{checkpoint_id}/consistency`,
+`/v2/witness/policies/{policy_id}`, `/v2/anchors/{anchor_epoch_id}`,
+`/v2/ivc/epochs/{ivc_epoch_id}`, `/v2/audit/packs`, and `/v2/verify`
+APIs. Single and batch writes both return signed receipts. It exposes witness
+policy and review-gated IVC epoch visibility. Receipt ingest can run before
+enforced rollout gates; verifier-bundle export requires witnessed and confirmed
+anchored checkpoints. Nova proof production remains review-gated until that
+rollout gate is enabled.
+
+## Signed webhook connectors
+
+Use the connector helper when an external source posts to a signed-webhook
+connector endpoint:
+
+```python
+import json
+from attesto import signed_connector_webhook_headers
+
+body = json.dumps({"sourceRef": "evt_123"}, separators=(",", ":")).encode()
+headers = signed_connector_webhook_headers(connector_secret, body)
+```
+
+The helper signs `timestamp + "." + raw_body_bytes` and returns the exact
+`X-Attesto-Connector-*` headers expected by
+`/v2/connectors/signed-webhooks/{connectorId}/events`.
+
+## Batching
+
+```python
+attesto.log_events([
+    {"type": "inference", "latency_ms": 40},
+    {"type": "inference", "latency_ms": 33},
+    {"type": "decision", "status": "pending", "payload": {"threshold": 0.7}},
+])
+```
+
+Up to 1000 events per batch. The Attesto worker then groups them into a
+Merkle tree and commits the root on Polygon mainnet within your tenant's
+configured cadence (6h / 1h / per-event).
+
+## Configuration
+
+| arg | default | purpose |
+|-----|---------|---------|
+| `api_key` | — | Required. Must match `atto_live_<32 lowercase hex chars>` or `atto_test_<32 lowercase hex chars>`. |
+| `base_url` | `https://verify.attesto.eu` | Public Attesto API origin. Override only for private/staging deployments. |
+| `timeout_s` | `10.0` | Per-request timeout. |
+| `max_retries` | `3` | Retries on 5xx / 429 / transport errors, with jittered exponential backoff. |
+| `user_agent` | `attesto-python/0.1.2` | Sent as the UA header. |
+
+## Error handling
+
+```python
+from attesto import (
+    AttestoClient,
+    AuthError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+try:
+    attesto.log_event(type="inference")
+except AuthError as exc:        # 401 / 403 — bad key
+    ...
+except RateLimitError as exc:   # 429 — exceeded tenant rate limit
+    ...
+except ValidationError as exc:  # 4xx payload problem
+    ...
+except ServerError as exc:      # 5xx after all retries exhausted
+    ...
+```
+
+All Attesto SDK exceptions expose `status` and `detail` when the server
+returned an HTTP response. Transport failures keep both as `None`.
+
+## What you get
+
+Every event:
+
+1. Canonicalised to byte-exact JSON (sort keys, no whitespace, ASCII-safe).
+2. SHA-256 hashed into a Merkle leaf.
+3. Batched with other events at your cadence.
+4. The Merkle root is committed on-chain via APSProvenance.
+5. Every anchored event gets a tenant-authenticated proof from
+   `GET /v1/events/{id}/proof`. The proof payload contains
+   `canonicalJson`, `proof`, and `batchId`; submit those fields to
+   `POST https://verify.attesto.eu/v1/public/verify` or paste them into
+   the `/verify` page for independent verification.
+
+You never handle keys, wallets, or gas — Attesto pays the gas and handles
+the on-chain flow.
+
+## Production behavior
+
+- Defaults to `https://verify.attesto.eu`; override `base_url` only for
+  private or staging deployments.
+- Use this SDK from server-side code only. Attesto system API keys are bearer
+  secrets and must never be embedded in browser bundles, mobile apps, logs, or
+  client-visible environment variables.
+- Validates the key shape locally before making network calls. Production
+  system keys are shown once when the system is registered in Attesto.
+- Validates `base_url` locally and accepts only `http` or `https` origins.
+- Adds an `Idempotency-Key` header automatically for single-event and batch writes.
+- Retries transient 429, 5xx, and transport failures with exponential backoff.
+- Caps batch ingestion at 1000 events per request.
+- Never handles wallets, private keys, or gas in application code.

attesto-0.1.2/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "attesto"
+version = "0.1.2"
+description = "Attesto AI Python SDK — log verifiable AI events to Polygon via one function call."
+requires-python = ">=3.10"
+readme = "README.md"
+license = "Apache-2.0"
+authors = [
+  { name = "Attesto", email = "info@attesto.eu" },
+]
+keywords = ["ai", "compliance", "eu-ai-act", "polygon", "merkle", "audit"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+  "httpx>=0.27",
+  "pydantic>=2",
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2",
+  "pytest>=8",
+  "pytest-asyncio>=0.24",
+  "pytest-httpx>=0.35",
+  "ruff>=0.7",
+]
+
+[project.urls]
+Homepage = "https://attesto.eu"
+Documentation = "https://docs.attesto.eu/manuals/sdks.html"
+Security = "https://attesto.eu/security"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

attesto-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

attesto-0.1.2/src/attesto/__init__.py

@@ -0,0 +1,124 @@
+"""Attesto AI Python SDK.
+
+Log every AI decision to a verifiable on-chain audit trail with one call:
+
+    from attesto import AttestoClient
+
+    attesto = AttestoClient(api_key="atto_live_...")
+    attesto.log_event(type="inference", status="verified", payload={"score": 0.87})
+
+Async? Use the same ergonomics:
+
+    from attesto import AsyncAttestoClient
+
+    async with AsyncAttestoClient(api_key="atto_live_...") as attesto:
+        await attesto.log_event(type="inference", status="verified")
+
+Every event you log is batched by the Attesto worker, hashed into a Merkle
+tree, and committed to Polygon mainnet. Your events become verifiable evidence
+for auditors under the EU AI Act.
+"""
+from attesto.client import DEFAULT_BASE_URL, AttestoClient, AttestoV2Client, VBPClient
+from attesto.connectors import (
+    sign_connector_webhook_payload,
+    signed_connector_webhook_headers,
+)
+from attesto.async_client import (
+    AsyncAttestoClient,
+    AsyncAttestoV2Client,
+    AsyncVBPClient,
+)
+from attesto.errors import (
+    AttestoError,
+    AuthError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from attesto.models import (
+    BatchResponse,
+    Event,
+    EventResponse,
+    ProofstreamAnchorEpoch,
+    ProofstreamCheckpoint,
+    ProofstreamCheckpointWindow,
+    ProofstreamConsistencyCheckpoint,
+    ProofstreamConsistencyProof,
+    ProofstreamEvent,
+    ProofstreamEventBatchResponse,
+    ProofstreamEventReceipt,
+    ProofstreamIvcEpoch,
+    ProofstreamOfflineVerifyReport,
+    ProofstreamReceiptSignature,
+    ProofstreamReceiptVerifyReport,
+    ProofstreamSignedReceipt,
+    ProofstreamStream,
+    ProofstreamStreamCreate,
+    ProofstreamStreamHead,
+    ProofstreamVerifyKind,
+    ProofstreamVerifierBundle,
+    ProofstreamWitnessPolicy,
+    ProofstreamWindow,
+    ProofstreamWindowLeaf,
+)
+from attesto.proofstream import (
+    PROOFSTREAM_DOMAINS,
+    PROOFSTREAM_PROTOCOL,
+    PROOFSTREAM_PROTOCOL_VERSION,
+    canonical_json,
+    canonical_json_bytes,
+    canonical_json_hex,
+    domain_hash_hex,
+    sha256_hex,
+)
+from attesto.version import __version__
+
+__all__ = [
+    "VBPClient",
+    "AttestoClient",
+    "AttestoV2Client",
+    "DEFAULT_BASE_URL",
+    "AsyncVBPClient",
+    "AsyncAttestoClient",
+    "AsyncAttestoV2Client",
+    "Event",
+    "EventResponse",
+    "BatchResponse",
+    "ProofstreamStreamCreate",
+    "ProofstreamStream",
+    "ProofstreamStreamHead",
+    "ProofstreamWitnessPolicy",
+    "ProofstreamAnchorEpoch",
+    "ProofstreamVerifierBundle",
+    "ProofstreamWindowLeaf",
+    "ProofstreamWindow",
+    "ProofstreamCheckpointWindow",
+    "ProofstreamCheckpoint",
+    "ProofstreamConsistencyCheckpoint",
+    "ProofstreamConsistencyProof",
+    "ProofstreamIvcEpoch",
+    "ProofstreamEvent",
+    "ProofstreamEventBatchResponse",
+    "ProofstreamReceiptSignature",
+    "ProofstreamSignedReceipt",
+    "ProofstreamEventReceipt",
+    "ProofstreamReceiptVerifyReport",
+    "ProofstreamOfflineVerifyReport",
+    "ProofstreamVerifyKind",
+    "PROOFSTREAM_DOMAINS",
+    "PROOFSTREAM_PROTOCOL",
+    "PROOFSTREAM_PROTOCOL_VERSION",
+    "canonical_json",
+    "canonical_json_bytes",
+    "canonical_json_hex",
+    "domain_hash_hex",
+    "sha256_hex",
+    "sign_connector_webhook_payload",
+    "signed_connector_webhook_headers",
+    "AttestoError",
+    "AuthError",
+    "RateLimitError",
+    "ServerError",
+    "ValidationError",
+    "__version__",
+]