Metadata-Version: 2.4
Name: salus-ai
Version: 0.3.6
Summary: Safety Infrastructure for AI Agents - Tool dependencies, channel integrity, and runtime protection
Author-email: Vedant Singh <vedant@usesalus.ai>
License-Expression: MIT
Project-URL: Homepage, https://salus.ai
Project-URL: Documentation, https://docs.salus.ai
Project-URL: Repository, https://github.com/salus-ai/salus
Project-URL: Issues, https://github.com/salus-ai/salus/issues
Keywords: llm,ai,safety,agents,openai,langchain,langgraph,crewai,anthropic,invariants,testing,stress-testing,runtime-safety
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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 :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML<7,>=6.0.0
Requires-Dist: fastapi<1,>=0.128.7
Requires-Dist: starlette<1,>=0.47.2
Requires-Dist: uvicorn[standard]<1,>=0.24.0
Requires-Dist: pydantic<3,>=2.5.0
Requires-Dist: python-multipart<1,>=0.0.6
Requires-Dist: jsonschema<5,>=4.20.0
Requires-Dist: loguru<1,>=0.7.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: alembic<2,>=1.13.0; extra == "dev"
Requires-Dist: asyncpg<1,>=0.29.0; extra == "dev"
Requires-Dist: cryptography<45,>=42.0.0; extra == "dev"
Requires-Dist: httpx<1,>=0.25.0; extra == "dev"
Requires-Dist: python-dateutil<3,>=2.8.0; extra == "dev"
Requires-Dist: slack_sdk<4,>=3.27.0; extra == "dev"
Provides-Extra: cli
Requires-Dist: pyyaml>=6.0.0; extra == "cli"
Provides-Extra: providers
Requires-Dist: openai>=1.0.0; extra == "providers"
Requires-Dist: anthropic>=0.18.0; extra == "providers"
Provides-Extra: validation
Requires-Dist: pydantic>=2.0.0; extra == "validation"
Requires-Dist: jsonschema>=4.0.0; extra == "validation"
Provides-Extra: reddit-digest
Requires-Dist: asyncpraw>=7.7.0; extra == "reddit-digest"
Requires-Dist: apscheduler>=3.10.0; extra == "reddit-digest"
Requires-Dist: openai>=1.0.0; extra == "reddit-digest"
Provides-Extra: encryption
Requires-Dist: cryptography>=41.0.0; extra == "encryption"
Provides-Extra: all
Requires-Dist: salus[cli,dev,encryption,providers,reddit-digest,validation]; extra == "all"
Dynamic: license-file

# Salus

[![CI](https://github.com/salus-inc/salus/actions/workflows/ci.yml/badge.svg)](https://github.com/salus-inc/salus/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**Enforcement layer for AI agent tool calls.** Salus sits between your agent and its tools, applying deterministic policy checks on every action before it executes. Allow, block, escalate, or revise -- outside the model, where prompt injection cannot reach.

---

## What it does

- **One decision per action** -- your agent asks Salus before each tool call; `/v1/decide` returns allow / block / escalate / revise, computed outside the model where prompt injection can't reach.
- **Policy is the authority** -- dashboard-authored field/operator/value rules, required facts, risk tiers, and brokering, all declared in one policy. No second hidden risk engine.
- **The wall, not a guardrail** -- for brokered tools the agent doesn't hold the credential. On allow, Salus mints a single-use grant; redeeming it (optionally executing the call server-side) is the only way to act. No allow → no grant → no action.
- **Repair in the same response** -- a non-allow returns a one-turn repair hint (collect a fact, ask the user, request approval) so the agent can recover, not just fail.
- **Shadow mode for safe rollout** -- observation-only with its own usage caps; see what *would* be blocked before enforcing.

## Enforcement scope

The **SDK** runs the full in-process enforcement pipeline (policy, contracts, evidence, repair); the **cloud proxy** evaluates the documented webhook-safe subset of those checks on proxied calls. See [docs/cloud-enforcement-scope.md](docs/cloud-enforcement-scope.md) for the exact split.

## What Salus is not

- Not an agent framework, planner, or model wrapper.
- Not a magic correctness guarantee.
- A bare `decide()` is advisory (cooperative). The hard guarantee comes from **brokering** (the agent can't act without a grant) — see [docs/PRODUCT_ARCHITECTURE.md](docs/PRODUCT_ARCHITECTURE.md).

---

## Quick start (SDK-first)

```bash
pip install usesalus        # Python      (or: npm i @usesalus/sdk for JS/TS)
```

```python
from salus import Salus

salus = Salus(api_key="sal_...", mode="enforce")

# Wrap the tool that causes the side effect (the executor, not the LLM call).
issue_refund = salus.protect("issue_refund", do_refund, side_effect=True)
issue_refund(order_id="ord_123", amount=42)   # authorized before it runs
```

Enforce at the **tool executor** — the boundary where the side effect happens — not around the model call. See [docs/SDK_QUICKSTART.md](docs/SDK_QUICKSTART.md).

---

## Architecture

**Cloud control plane** — where policies, secrets, traces, approvals, usage, and decisions live. `/v1/decide` runs the full pipeline (caps → conversation integrity → required facts/resolver → enforcement engine → policy rules → reasoning judge/RAG) and returns one envelope: `decision` + `repair` + `grant`.

**SDK enforcement point** — installed in the backend process that owns your tools. Calls `/v1/decide` before executing; for brokered tools, redeems the grant so the action can't happen without an allow.

The default configuration is fail-closed for enabled checks; operators can configure fail-open for selected failure modes. Full design: [docs/PRODUCT_ARCHITECTURE.md](docs/PRODUCT_ARCHITECTURE.md).

> **Proxy mode is legacy.** The webhook proxy (Retell/Vapi/generic HTTP) still exists for compatibility, but the SDK is the supported path. New integrations should use the SDK; the proxy is not recommended for new work.

---

## Supported platforms

| Mode | Platforms |
|------|-----------|
| Cloud proxy (voice) | Retell, Vapi, generic HTTP webhooks |
| SDK adapters | LangChain, AutoGen, CrewAI, LangGraph |
| LLM providers | OpenAI, Anthropic, Gemini |

---

## Key features

| Feature | Description |
|---------|-------------|
| Policy engine | Plain Python logic or field/operator/value rules. Dashboard editor. |
| Approval workflows | Escalate high-risk actions to human reviewers. Slack notifications, dashboard UI. |
| PII redaction | Automatic detection and redaction of sensitive fields. Fail-closed. |
| Shadow mode | Log decisions without blocking. Validate policy changes before enforcement. |
| Voice output guard | Response checks for supported voice proxy responses. |
| Usage metering | Daily and monthly billable action tracking with configurable quota limits. |
| Session tracking | Cloud-safe session checks in the proxy; richer stateful controls in the SDK. |
| Policy versioning | Version and audit policy changes over time. |

---

## Documentation

| Topic | Link |
|-------|------|
| Local quickstart | [docs/QUICKSTART.md](docs/QUICKSTART.md) |
| Cloud quickstart | [docs/CLOUD.md](docs/CLOUD.md) |
| Cloud setup and deploy | [docs/cloud-setup-guide.md](docs/cloud-setup-guide.md) |
| Cloud vs SDK scope | [docs/cloud-enforcement-scope.md](docs/cloud-enforcement-scope.md) |
| Integration guide | [docs/INTEGRATION.md](docs/INTEGRATION.md) |
| Advanced integration | [docs/INTEGRATION_ADVANCED.md](docs/INTEGRATION_ADVANCED.md) |
| Adapter migration | [docs/adapter-migration-guide.md](docs/adapter-migration-guide.md) |
| Retell setup | [docs/guides/retell-setup.md](docs/guides/retell-setup.md) |
| Vapi setup | [docs/guides/vapi-setup.md](docs/guides/vapi-setup.md) |
| Security and privacy | [docs/cloud-security.md](docs/cloud-security.md) |
| Context-to-enforcement architecture | [docs/CONTEXT_TO_ENFORCEMENT.md](docs/CONTEXT_TO_ENFORCEMENT.md) |
| API reference | Run the server and visit `/docs` |

---

## Security

Salus' hosted default configuration is fail-closed for enforcement errors unless an operator explicitly configures fail-open behavior for a tool.

Workspace isolation scopes tenant data by workspace. API keys are stored as HMAC digests using a server-side pepper and are returned only once at creation. Request size limits, rate limiting, and security headers (HSTS, X-Content-Type-Options, X-Frame-Options) are applied to hosted routes. The cloud container runs as a non-root user.

See [docs/cloud-security.md](docs/cloud-security.md) for the full security model.

---

## License

MIT -- see [LICENSE](LICENSE).

## Legal

- [Privacy Policy](https://salus.sh/privacy)
- [Terms of Service](https://salus.sh/terms)

---

*salus* -- Latin for *safety*.
