nexus-evidence-sdk 0.1.0

Nexus Evidence Platform · Python SDK (NexusClient + nx.trace + HMAC auth)

nexus-ai-sdk · Python SDK

Client SDK for the Nexus Evidence Platform · EU AI Act compliance + observability.

Status: alpha (0.1.0) · sem 2 H1 · NOT yet published to PyPI (gate operador sem 3+).

Canon: ADR-037 §SDK contract languages · ADR-036 §Ingestion architecture · ADR-041 §Data residency boundary.

Install

Once published to PyPI:

pip install nexus-ai-sdk

For local development from this monorepo:

pip install -e sdk/python

Quickstart

from nexus_sdk import NexusClient

nx = NexusClient(
    api_key="nexus_tenant_abc123",
    tenant_id="<your-tenant-uuid>",
    system_id="hr-screening-v3",
    endpoint="http://127.0.0.1:8400",  # data-plane gateway local
    environment="production",
    sovereignty="eu",
)

with nx.trace(operation="candidate_screening", context={"job_id": "J-123"}):
    resp = anthropic_client.messages.create(
        model="claude-opus-4-7",
        messages=[...],
    )
    nx.attach_output(resp, classification="candidate_rank")

Architecture

The SDK sends IngestEvent payloads via HTTPS+HMAC to the data-plane gateway running locally (or in a Nexus-managed VPS). Raw prompts + responses never leave the data plane. Only aggregated metadata (counters, hashes, heartbeats) crosses to the control plane.

See adrs/ADR-036-ingestion-architecture.md for the full flow and adrs/ADR-041-data-residency-boundary.md for the boundary rules.

HMAC scheme

Each request is signed with HMAC-SHA256 using the tenant API key. Headers emitted:

X-Nexus-Tenant-Id:  <tenant_uuid>
X-Nexus-Timestamp:  <UTC ISO8601 second precision>
X-Nexus-Signature:  sha256=<hex>
Content-Type:       application/json

The signature canonicalizes the JSON body with sort_keys=True and compact separators, ensuring reproducibility cross-language (Python ↔ TypeScript SDK).

Errors

from nexus_sdk import NexusError, NexusAuthError, NexusValidationError

try:
    nx.send_event(event)
except NexusAuthError:
    # Rotate api_key via control plane
    ...
except NexusValidationError as e:
    print("schema rejected:", e.response_body)
except NexusError as e:
    # Network / generic gateway error
    ...

License

Proprietary · © Nexus Evidence Platform