Nyraxis Python SDK

This source tree contains the 1.3.1 release. Package recovery and verified behavior are recorded in ../COMPATIBILITY.md. For local SDK development, use an editable install:

python -m venv .venv
.venv\Scripts\python -m pip install -e sdk/python

From the backend repository, set NYRAXIS_API_KEY to an ingest-scoped key and NYRAXIS_BASE_URL to the API you intend to evaluate against. Never put a key in source control.

import os
from nyraxis_sdk import NyraxisClient

with NyraxisClient(
    api_key=os.environ["NYRAXIS_API_KEY"],
    base_url=os.environ["NYRAXIS_BASE_URL"],
    agent_name="support-agent",
) as client:
    result = client.evaluate(
        input="Synthetic support request for a test account",
        capture_mode="metadata",
    )
    print(result.evaluation_status, result.allowed, result.trace_id)
    print(result.violations, result.errors)

An allowed result is meaningful only alongside evaluation_status and errors. A missing, degraded, or not_configured status is not a completed clean check. not_configured means the organization has no enabled policy; enable one in the dashboard and rerun this example before claiming coverage. The result depends on the organization's actual policies and available detectors; this example does not assert a particular finding. Evaluation text is sent to the configured API even when stored trace capture is metadata only. The organization's capture setting is the ceiling; no_trace=True is stricter.

Pre-call enforcement

nyraxis_sdk.init(..., enforce=True) patches specific supported provider methods. It evaluates extracted user text before those methods run and raises NyraxisBlockedError on an explicit blocking result. For a required check, configure enforce_fail_open=False, enforce_require_complete=True, and enforce_cache_ttl_s=0; the published default is fail open, and a cached allow can outlive a policy edit. Set an enforce_timeout_s that fits your backend's measured cold and steady-state latency. The five-second default timed out on one cold isolated test path; the verified local fixture used 30 seconds. A timeout with fail-open enabled can allow the provider call without a completed check. Catch the exception and inspect policy metadata without logging the original prompt. enforce_require_complete=True raises NyraxisError when an allowed response is degraded, unavailable, not configured, or reports detector errors. An explicit blocking decision still raises NyraxisBlockedError. The option is off by default to preserve existing callers. With it disabled, fail-closed network behavior alone does not reject an incomplete response. NyraxisBlockedError.input_preview remains an empty compatibility attribute in this release.

Interception does not cover arbitrary model or tool calls, images, audio, or every streaming/output path. Direct evaluate() only reports a decision; your application must act on it. The provider matrix and test limits are in the compatibility document. Instrumentation is a separate opt-in integration. One synthetic OTLP span from the clean-installed package reached the isolated backend and survived flush/shutdown; individual provider instrumentors remain unverified.

Instrumentation content boundary

instrument=True configures Traceloop and can send prompt/completion span attributes to the configured Nyraxis API. The package preserves this existing default. To request suppression, set instrument_capture_content=False in nyraxis_sdk.init(...). This sets TRACELOOP_TRACE_CONTENT=false even if the process previously set it to true; an existing false setting is never widened. Traceloop documents this flag as its prompt-content switch. One manually attributed synthetic OTLP span was exported and stored without its prompt marker under metadata-only capture. This does not verify suppression by each provider instrumentor. Direct evaluate() still sends its input to the configured API, and metadata-only storage remains a separate setting.

Verify the package

$env:PYTHONPATH='sdk/python'
python -B -m pytest sdk/python/tests -q -c sdk/python/pyproject.toml -p no:cacheprovider
python -m build --wheel --no-isolation sdk/python

A clean-installed wheel passed a narrow marked PostgreSQL/API check and real OpenAI 3.19.2 pre-call blocking test. Other provider versions, streaming/output behavior, provider-specific instrumentation and release provenance remain open. The README evaluation snippet executed from the clean-installed wheel against the isolated API; its no-policy result was not_configured. See ../COMPATIBILITY.md.