Metadata-Version: 2.4
Name: nyraxis-sdk
Version: 1.3.1
Summary: AI guardrails for production — evaluate LLM inputs and outputs against governance policies.
Author-email: Nyraxis <support@nyraxis.io>
License-Expression: MIT
Project-URL: Homepage, https://nyraxis.io
Project-URL: Documentation, https://nyraxis.io/docs
Keywords: guardrails,llm,ai-safety,governance,pii,content-moderation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Security
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.28.0
Provides-Extra: instrument
Requires-Dist: traceloop-sdk<1.0.0,>=0.33.0; extra == "instrument"
Requires-Dist: opentelemetry-api>=1.20.0; extra == "instrument"
Requires-Dist: requests<3.0.0,>=2.32.0; extra == "instrument"
Provides-Extra: cli
Requires-Dist: typer>=0.12.0; extra == "cli"
Dynamic: license-file

# Nyraxis Python SDK

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

```powershell
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.

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

```powershell
$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`](../COMPATIBILITY.md).
