Metadata-Version: 2.4
Name: niansys
Version: 0.1.1
Summary: Monitoring & security SDK for autonomous AI agents — observe what agents do, not what they say.
Project-URL: Homepage, https://github.com/gildasassande/niansys
Project-URL: Documentation, https://github.com/gildasassande/niansys#readme
Project-URL: Repository, https://github.com/gildasassande/niansys
Project-URL: Issues, https://github.com/gildasassande/niansys/issues
Project-URL: Changelog, https://github.com/gildasassande/niansys/blob/main/CHANGELOG.md
Author-email: Gildas Assande <gildaskassi01@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agents,ai,guardrails,llm,monitoring,observability,security
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: respx>=0.20.2; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# NIANSYS Python SDK

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

[![Tests](https://github.com/gildasassande/niansys/actions/workflows/ci.yml/badge.svg)](https://github.com/gildasassande/niansys/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

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

```bash
pip install niansys
```

> Requires Python 3.10+.

## Quickstart

```python
from niansys import Guardian

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

result = guardian.check(
    action="send_email",
    target="ceo@acme.com",
    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:

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

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

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

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

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

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

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

## Examples

Runnable scripts live in [`examples/`](./examples):

- **[`openai_integration.py`](./examples/openai_integration.py)** — Plug NIANSYS into an OpenAI tool-calling agent. Every tool call validated before execution.
- **[`concurrent_batch.py`](./examples/concurrent_batch.py)** — Validate 50+ actions in parallel via `asyncio.gather`. Showcase of the async API.

See [`examples/README.md`](./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](./CHANGELOG.md).

## Contributing

Bug reports and pull requests welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md).

## License

[MIT](./LICENSE) — use it, fork it, build on it.

## Author

Built by **[Gildas Assande](https://github.com/gildasassande)**. Feedback, issues, and PRs welcome.
