niansys 0.1.1

Monitoring & security SDK for autonomous AI agents — observe what agents do, not what they say.

NIANSYS Python SDK

Monitoring & security for autonomous AI agents. Observe what your agents do, not what they say.

NIANSYS is the trust layer between your AI agents and the systems they touch — emails, databases, payments, files, APIs. Other tools watch what your agent says (prompts, tokens, latency). NIANSYS watches what your agent does, scores the risk, and — when you ask it to — blocks dangerous actions in real time.

This repository is the official Python SDK: open-source, minimal, async-friendly.

---

Install

pip install niansys

Requires Python 3.10+.

Quickstart

from niansys import Guardian

guardian = Guardian(agent_key="iag_...")  # get one from the NIANSYS dashboard

result = guardian.check(
    action="send_email",
    target="[e-mail]",
    metadata={"subject": "Q4 results", "body_length": 1240},
)

if result.allowed:
    send_email(...)
else:
    print(f"Blocked by NIANSYS: {result.reason}")

The recommended pattern is the context manager — it releases the underlying HTTP connection pool when you're done:

with Guardian(agent_key="iag_...") as guardian:
    result = guardian.check(action="run_sql", target="prod.users")

Async

Guardian ships with a native async API — same shape, just await-able:

async with Guardian(agent_key="iag_...") as guardian:
    result = await guardian.acheck(
        action="run_sql",
        target="prod.users",
        metadata={"query": "DELETE FROM users WHERE ..."},
    )

And the killer feature — validate many actions in parallel:

import asyncio

async with Guardian(agent_key="iag_...") as guardian:
    results = await asyncio.gather(*(
        guardian.acheck(action="send_email", target=addr)
        for addr in recipient_list
    ))

Modes

The same SDK supports two modes, switchable per-agent:

• observe (default) — NIANSYS logs and scores every action, but result.allowed is always True. Zero friction, ideal to start.
• control — NIANSYS can return result.allowed = False based on policies, baselines, or risk score. Honor the decision in your code.

guardian = Guardian(agent_key="iag_...", mode="control")

Fail-open vs fail-closed

What happens when the NIANSYS cloud is unreachable or returns a 5xx error? You decide:

# Default — fail-open: the agent keeps working. result.allowed = True, the call is dropped.
Guardian(agent_key="iag_...")

# High-security — fail-closed: NiansysNetworkError / NiansysServerError is raised, the agent aborts.
Guardian(agent_key="iag_...", fail_open=False)

The SDK retries network errors and 5xx responses 3 times with exponential backoff (0.5s → 1s → 2s) before applying this policy. 4xx errors (auth, validation, rate-limit) are never retried — they signal a real issue the developer must fix.

The right answer depends on your risk profile. Most production agents start with fail_open=True and tighten over time.

Exceptions

All SDK errors inherit from NiansysError:

from niansys import (
    NiansysError,            # catch-all base
    NiansysAuthError,        # 401 / 403 — invalid key, suspended agent
    NiansysValidationError,  # 400 / 422 — malformed payload
    NiansysRateLimitError,   # 429
    NiansysServerError,      # 5xx after retries (fail_open=False only)
    NiansysNetworkError,     # transport failure after retries (fail_open=False only)
)

Typed

niansys is fully typed (PEP 561). mypy and pyright pick up types automatically when you pip install niansys — no extra stubs needed.

Self-hosting / local dev

By default the SDK talks to the public NIANSYS cloud at https://api.niansys.com. Override base_url to point at your own deployment or a local backend:

guardian = Guardian(
    agent_key="iag_...",
    base_url="http://127.0.0.1:8000",  # local NIANSYS backend
)

Examples

Runnable scripts live in examples/:

• openai_integration.py — Plug NIANSYS into an OpenAI tool-calling agent. Every tool call validated before execution.
• concurrent_batch.py — Validate 50+ actions in parallel via asyncio.gather. Showcase of the async API.

See examples/README.md for details.

Why NIANSYS

Agents IA now run real actions in real systems. They send emails, execute SQL, move money, write to disk. The capabilities are progressing faster than the tools to govern them.

• Langfuse / Helicone / LangSmith / Arize watch prompts and costs.
• Lakera watches prompt-injection attacks.
• Datadog watches the infrastructure.

None of them watch the action layer — what the agent actually does. That's where NIANSYS lives.

Status

v0.1.1 — early alpha. The public API (Guardian, check, acheck, CheckResult) is stable. Internals may move. Production deployments are coordinated case-by-case until v1.0.

Changelog

See CHANGELOG.md.

Contributing

Bug reports and pull requests welcome. See CONTRIBUTING.md.

License

MIT — use it, fork it, build on it.

Author

Built by Gildas Assande. Feedback, issues, and PRs welcome.