Nyraxis Python SDK

Release 1.3.2 contains the streaming, lifecycle and response-integrity fixes described below. Earlier 1.3.1 does not include them. 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.

Streaming and shutdown in 1.3.2

@nyraxis_sdk.traced(...) now follows Python generator and async-generator consumption, including early close, cancellation, send/throw and async send/throw. One parent span lives until the producer finishes or closes; its context is attached only while the producer executes. It does not leak into the consumer between chunks. This is tracing, not an output-chunk blocking guarantee. Explicitly close partially consumed streams.

Stop producers and close streams before shutdown. Synchronous applications call nyraxis_sdk.shutdown(timeout_millis=30000); asynchronous applications must await nyraxis_sdk.shutdown_async(timeout_millis=30000) to close both HTTP clients without blocking the event loop during flush. Configured instrumentation is flushed before cleanup; an uncompleted flush raises NyraxisError, and HTTP clients are still closed. The application's process tracer provider is not shut down by the SDK.

nyraxis_sdk.flush(timeout_millis=30000) returns the tracer provider's flush completion result. True is not successful transport or durable-storage proof: processors can finish after an exporter failure. Verify backend trace receipt separately. Unconfigured optional tracing has nothing to flush.

Malformed evaluation decisions raise InvalidEvaluationResponse, including when enforcement's transport fail-open option is enabled. HTTP 403 remains denied with HTML, null or array error bodies. Genuine transport-error policy is unchanged; logs record the exception type, not its message payload.

Local evidence uses real OpenTelemetry providers and an OTLP/HTTP localhost receiver, plus an isolated native PostgreSQL authentication clone. It does not establish a real customer/framework/provider deployment, Node streaming support, independent onboarding, remote alert receipt or production acceptance. The release preserves these integration limits; SDK publication is not product or detector acceptance.

Clean release installation

Install the exact release into a fresh environment:

python -m venv .venv
.venv\Scripts\python.exe -m pip install nyraxis-sdk==1.3.2
.venv\Scripts\python.exe -m pip check

For an owned localhost support rehearsal, use the support pilot instructions. They describe explicit manual OpenTelemetry prerequisites, sync/async stream closure, flush, awaited shutdown and sanitized errors. The recorded 1.3.2.dev0 private rehearsal remains historical evidence; release artifacts have their own hashes and tests. Real-provider, independent-operator and customer-production acceptance remain open.