Metadata-Version: 2.4
Name: nexus-legal
Version: 0.1.1
Summary: Official Python SDK for the Nexus Legal API v1 — multi-jurisdictional legal analysis with certainty locks, async jobs, signed webhooks, organizations and sub-keys.
Project-URL: Homepage, https://nexusquantum.legal/developers
Project-URL: Documentation, https://nexusquantum.legal/developers/docs
Project-URL: Repository, https://github.com/djtellado/nexus-legal-prod
Project-URL: Issues, https://github.com/djtellado/nexus-legal-prod/issues
Project-URL: Changelog, https://nexusquantum.legal/developers/changelog
Author-email: Nexus Legal <support@nexusquantum.legal>
License: MIT
License-File: LICENSE
Keywords: ai,api-client,iso-31000,law,legal,legaltech,llm,nexus-legal,sdk,spanish-law
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Legal Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: requests>=2.28.0
Provides-Extra: test
Requires-Dist: pytest-mock>=3.10; extra == 'test'
Requires-Dist: pytest>=7.0; extra == 'test'
Requires-Dist: responses>=0.23; extra == 'test'
Description-Content-Type: text/markdown

# nexus-legal

[![PyPI version](https://img.shields.io/pypi/v/nexus-legal.svg)](https://pypi.org/project/nexus-legal/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Official **Python SDK** for the [Nexus Legal](https://nexusquantum.legal) API v1 — multi-jurisdictional legal analysis with defensible certainty locks, vector case-law search, async jobs, signed webhooks, organizations and sub-keys.

```bash
pip install nexus-legal
```

Requires Python ≥ 3.9.

## Quick start

```python
import os
from nexus_legal import NexusClient

nexus = NexusClient(api_key=os.environ["NEXUS_API_KEY"])

result = nexus.analyze(
    text="Por el presente contrato, el arrendador cede el uso…",
    jurisdiction="ES",
    legal_branch="civil",
)

print(result["analysis"])
print("Rate limit remaining:", result["rate_limit"]["remaining"])
```

Get an API key at [`/developers`](https://legal.nexusquantum.legal/developers). Full docs at [`/developers/docs`](https://legal.nexusquantum.legal/developers/docs).

## Features

- **Synchronous** — built on `requests`. Async (httpx) coming in a future release.
- **Auto idempotency** — every `POST` carries an auto-generated `Idempotency-Key` (UUID4) reused across retries → no double-charge.
- **Smart retries** — 429 / 5xx with exponential backoff + jitter, honoring `Retry-After`.
- **Typed errors** — `RateLimitError`, `InsufficientCreditsError`, `IdempotencyConflictError`, `ValidationError`, `AuthenticationError`, `ServerError`, `TimeoutError`.
- **Rate-limit telemetry** — every response exposes `result["rate_limit"]`.
- **Audit-trail parser** — `extract_audit_trail()` returns a structured `TypedDict` without any YAML dependency.
- **Webhook signature verification** — `verify_webhook_signature()` for incoming HMAC-signed deliveries.

## API surface

```python
nexus = NexusClient(
    api_key="nlk_...",
    base_url="https://nexusquantum.legal",   # default
    timeout=120.0,                            # seconds
    max_retries=3,
    auto_idempotency=True,
)

# Sync
nexus.analyze(text=..., jurisdiction="ES", legal_branch="civil")
nexus.analyze_batch(documents=[...], concurrency=5)

# Sandbox (no credits)
nexus.sandbox.analyze(sample="providencia_aeat")
nexus.sandbox.metadata()

# Case-law search
nexus.jurisprudencia.search(query="...", jurisdiction="ES", top_k=5)

# Catalogs and usage
nexus.jurisdictions.list()
nexus.usage.get(from_="2026-04-01", to="2026-05-01", granularity="day")
nexus.usage.csv(from_="2026-04-01", to="2026-05-01")

# Async jobs
job = nexus.jobs.create(kind="analyze", payload={"text": ..., "jurisdiction": "ES"})
snap = nexus.jobs.get(job["jobId"])
final = nexus.jobs.run(kind="analyze", payload={...})   # poll helper

# Webhooks
wh = nexus.webhooks.create(url="https://example.com/hook", events=["analysis.completed"])
print("Secret:", wh["secret"])   # shown once

# Organizations + sub-keys
org = nexus.organizations.create(name="Mi Despacho LATAM")
sk  = nexus.organizations.create_key(org["organization"]["id"], child_label="Despacho Vázquez")
```

## Error handling

```python
from nexus_legal import (
    InsufficientCreditsError,
    RateLimitError,
    ValidationError,
)

try:
    nexus.analyze(text=text, jurisdiction="ES")
except InsufficientCreditsError as e:
    print(f"Need {e.required}, have {e.balance}")
except RateLimitError as e:
    time.sleep(e.retry_after)
except ValidationError as e:
    print(f"Bad request: {e}")
```

## Webhook signature verification

```python
import os
from nexus_legal import verify_webhook_signature
from flask import Flask, request

app = Flask(__name__)

@app.post("/nexus-webhook")
def webhook():
    raw = request.get_data()                       # bytes, pre-parse
    sig = request.headers.get("X-Nexus-Signature")
    if not verify_webhook_signature(
        raw_body=raw,
        signature=sig,
        secret=os.environ["WEBHOOK_SECRET"],
    ):
        return ("invalid signature", 401)
    payload = request.get_json()
    # ...
```

## Audit-trail parsing

```python
from nexus_legal import extract_audit_trail

trail = extract_audit_trail(result["analysis"])
if trail and trail["levels_emitted"].get("L5-C", 0) > 0:
    # Critical contractual risk — escalate to human reviewer
    ...
```

The parser handles `levels_emitted`, `review_flags`, `modules_active`, `kill_switches_triggered`, `rag_sources`, `executive_summary` and exposes the raw YAML in `trail["raw"]` for callers who want to re-parse with PyYAML.

## Versioning

This SDK targets API **v1.x** and follows SemVer:

- **MAJOR** — drops support for an API breaking change.
- **MINOR** — new endpoints, new fields, new options.
- **PATCH** — bug fixes, doc improvements.

See the [API changelog](https://legal.nexusquantum.legal/developers/changelog).

## License

MIT — see [`LICENSE`](./LICENSE).

---

Built by [Nexus Legal](https://nexusquantum.legal). Questions? Email [support@nexusquantum.legal](mailto:support@nexusquantum.legal).
