Python SDK

Configure evaluation, input enforcement, tracing, and lifecycle in nyraxis-sdk 1.3.2.

Install

Terminal

python -m venv .venv
python -m pip install nyraxis-sdk==1.3.2

Activate the environment using your operating system's standard command before installing. For auto-instrumentation, install "nyraxis-sdk[instrument]==1.3.2". The base package alone does not configure a telemetry exporter.

Set NYRAXIS_API_KEY to an ingest-scoped key and NYRAXIS_BASE_URL to your backend API origin. Keep both SDK and model-provider secrets on the server.

Direct client

evaluate.py

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",
    timeout=30,
) as client:
    result = client.evaluate(
        input="What are your support hours?",
        capture_mode="metadata",
    )
    complete = (
        result.evaluation_status == "complete"
        and not result.errors
        and result.policies_evaluated > 0
    )
    if not complete:
        raise RuntimeError("Required evaluation did not complete")
    print({"allowed": result.allowed, "trace_id": result.trace_id})

evaluate() returns a decision. Put the branch that stops your model call or output release after this result. A network, access, or malformed-response error raises; the direct client does not silently turn it into an allow.

Evaluation arguments

Argument	Default	Purpose
`input`	Required	Non-empty text; also required when evaluating `output`.
`output`	`None`	Proposed output to evaluate with the input.
`agent_name`	Client's configured name	Resolves the agent scope.
`policies`	`None`	Optional detector-type selection; normally use configured policies.
`mode`	`"thorough"`	`"thorough"` or `"fast"`; see depth semantics.
`capture_mode`	`None`	May reduce the organization's capture permission to `"metadata"`.
`no_trace`	`False`	Skip evaluation trace recording.

Response fields

The Python dataclass uses the API's snake_case names: allowed, violations, latency_ms, mode, policies_evaluated, trace_id, evaluation_status, errors, policy_versions, and capture_mode.

Each violation has policy_type, severity, description, and details. Do not log raw descriptions or workload content by default. See response interpretation.

Asynchronous evaluation

async_evaluate.py

import asyncio
import os
from nyraxis_sdk import NyraxisClient

async def main():
    async with NyraxisClient(
        api_key=os.environ["NYRAXIS_API_KEY"],
        base_url=os.environ["NYRAXIS_BASE_URL"],
        agent_name="support-agent",
    ) as client:
        result = await client.evaluate_async(
            input="Synthetic support question",
            capture_mode="metadata",
        )
        if (result.evaluation_status != "complete"
                or result.errors or result.policies_evaluated < 1):
            raise RuntimeError("Required evaluation did not complete")
        print({"allowed": result.allowed, "trace_id": result.trace_id})

asyncio.run(main())

Use close() for a synchronous client and await close_async() for asynchronous use, or the context managers above.

Process-wide initialization

nyraxis_sdk.init() configures the module-level client and optional process-wide instrumentation/interception. Initialize once during application startup.

Argument	Default	Purpose
`api_key`	Required	Issued Nyraxis key.
`base_url`	`https://api.nyraxis.io`	Backend API origin.
`agent_name`	`"nyraxis-agent"`	Instrumented agent identity.
`agent_version`	`None`	Optional version metadata.
`instrument`	`False`	Configure supported Traceloop instrumentation; requires the extra.
`instrument_capture_content`	`True`	Set `False` to request prompt/completion attribute suppression.
`enforce`	`False`	Enable supported input interceptors.
`enforce_fail_open`	`True`	Allow provider execution on genuine evaluator transport failure.
`enforce_require_complete`	`False`	Reject allowed decisions with incomplete status or evaluation errors.
`enforce_timeout_s`	`5.0`	Evaluation HTTP timeout in seconds.
`enforce_cache_ttl_s`	`60.0`	Cache repeated input decisions; zero disables caching.

For required checks, explicitly set fail-closed and completion behavior. A cached decision can outlive a policy edit. Enforcement covers exact scope and failures.

Errors

NyraxisBlockedError: a supported interceptor rejected the input.
GovernanceBlocked: the direct client received HTTP 403; this can be an access denial.
InvalidEvaluationResponse: the decision is malformed; never treat it as an allow.
NyraxisError: SDK errors, including incomplete required checks and failed instrumentation shutdown acknowledgement.
HTTP and network exceptions: preserve the application's failure policy; return a controlled error and avoid logging bodies.

Shutdown

After closing active streams, call nyraxis_sdk.shutdown() for synchronous use or await nyraxis_sdk.shutdown_async() for async use. flush(timeout_millis=30000) requests exporter completion; verify receipt in the backend separately. The SDK does not shut down an application-owned tracer provider.

Continue with tracing or the live LangGraph integration.

On this page