Metadata-Version: 2.4
Name: nexus-evidence-sdk
Version: 0.1.0
Summary: Nexus Evidence Platform · Python SDK (NexusClient + nx.trace + HMAC auth)
Project-URL: Homepage, https://nexus-ai.eu
Project-URL: Documentation, https://docs.nexus-ai.eu/sdk/python
Project-URL: Repository, https://github.com/nexus-ai-eu/nexus-platform
Project-URL: Issues, https://github.com/nexus-ai-eu/nexus-platform/issues
Author-email: Nexus Evidence Platform <sdk@nexus-ai.eu>
License: Apache-2.0
License-File: LICENSE
Keywords: ai,compliance,eu-ai-act,evidence,observability
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# 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:
```bash
pip install nexus-ai-sdk
```

For local development from this monorepo:
```bash
pip install -e sdk/python
```

## Quickstart

```python
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

```python
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
