Metadata-Version: 2.4
Name: guardledger
Version: 0.1.0
Summary: Sentinel — compliance-grade flight recorder + kill switch for AI agents
Author: Itamar Meirovich
License: Apache-2.0
License-File: LICENSE
Keywords: agent-governance,ai-agents,ai-security,audit,compliance,eu-ai-act,guardrails,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.110
Requires-Dist: pyyaml>=6.0
Requires-Dist: uvicorn>=0.29
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: mcp>=1.0; extra == 'dev'
Requires-Dist: opentelemetry-sdk>=1.20; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: otel
Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
Description-Content-Type: text/markdown

# Sentinel

[![CI](https://github.com/itamarmeirovichai-source/sentinel/actions/workflows/ci.yml/badge.svg)](https://github.com/itamarmeirovichai-source/sentinel/actions/workflows/ci.yml)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)

**The compliance-grade flight recorder + kill switch for AI agents.**

Sentinel sits between **any** AI agent (any framework) and its tools. Every action is
checked against your policy *before* it runs, recorded into a tamper-evident
audit trail you can replay and export as compliance evidence, and you can stop
the agent instantly. The point is provability: knowing — and being able to
prove — exactly what your agent did.

> Status: **MVP / alpha (v0.1).** This is the narrow wedge of a larger vision (see
> [RESEARCH.md](RESEARCH.md) and [ROADMAP.md](ROADMAP.md)). It is **not** another
> prompt-injection filter — it leads with deterministic enforcement + provable audit.
>
> ⚠️ **Disclaimer.** Experimental; APIs may change; provided "as is", no warranty
> (Apache-2.0). Compliance mappings (EU AI Act Art. 12, OWASP) are **indicative
> engineering aids — not legal advice or a certification**. You remain responsible for
> your own compliance and for reviewing Sentinel before relying on it in high-stakes systems.

## Why

Teams can't get sign-off to let agents touch high-stakes systems (trading,
billing, prod DBs) because there's no audit-grade record of what the agent did,
no enforcement of what it's allowed to do, and no instant stop. Regulation now
forces the issue: **EU AI Act Article 12** mandates automatic event logging for
high-risk systems (enforcement from **2026-08-02**). Sentinel is the layer that
produces that evidence. Full market/competitive analysis: [RESEARCH.md](RESEARCH.md).

## Core guarantees

- **Default-deny** — an action with no matching allow rule is blocked.
- **Fail-closed** — if the decision core itself errors, the action is blocked, not run.
- **Tamper-evident** — the audit log is hash-chained; any edit/reorder/delete is detectable via `verify`.

## Architecture (one glance)

```
agent ─tool_call─► Interceptor ─► KillSwitch? ─► Detector(flags) ─► Policy(default-deny)
                                                                         │
                              audit (hash-chained, redacted) ◄── execute / block
```

Interception is an SDK wrapper today, behind an `Interceptor` interface so an
MCP-proxy adapter slots in later without touching the policy/audit/kill core.
Details + threat model: [ARCHITECTURE.md](ARCHITECTURE.md).

## Quickstart

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env

# run the tests (security-critical core is tested first)
pytest

# run the end-to-end demo (a generic agent; see DEMO.md)
python examples/generic_agent.py        # or: sentinel demo

# launch the control API + dashboard
sentinel serve            # then open http://127.0.0.1:8787
```

> Shortcut: `make install && make test && make demo`.
> On PyPI the package is **`guardledger`** (the `sentinel` handle is taken); the import
> name and CLI stay `sentinel` — `pip install guardledger` → `import sentinel`.

## Usage sketch

```python
from sentinel import Sentinel

sentinel = Sentinel.from_files(policy="policies/starter.yaml", db="data/sentinel.db")

@sentinel.guard                      # every call is checked, logged, killable
def send_email(to: str, subject: str, body: str): ...

# …or guard a whole toolset at once:
tools = sentinel.wrap_all({"send_email": send_email, "search_web": search_web})

# over-policy / killed / suspicious calls raise BlockedError and are recorded;
# allowed calls run normally and are recorded with their outcome.
```

## Works with any agent, any framework

Plain Python functions, LangChain, OpenAI Agents SDK, CrewAI, LlamaIndex, or MCP — guard
your tools with `@sentinel.guard` / `sentinel.wrap_all(...)`, or use the MCP proxy/server.
See [INTEGRATIONS.md](INTEGRATIONS.md). The default demo (`sentinel demo`) is a generic
agent; [`examples/trading_agent.py`](examples/trading_agent.py) is a vertical example.

## Two interceptors, one core

The SDK wrapper is the default. For agents that reach tools over **MCP**, the same
enforcement (`Sentinel.enforce`) runs behind a proxy — nothing the agent calls can
bypass it:

```python
from sentinel import MCPProxy, SentinelMCPServer

proxy = MCPProxy(sentinel, upstream=my_mcp_session)   # guard calls to upstream MCP servers
server = SentinelMCPServer(sentinel)                  # OR expose your own tools over MCP
server.add_tool("get_quote", get_quote)               #    with enforcement built in
```

Install the optional transports with `pip install "guardledger[mcp,otel]"`.

## Operating it

- **Monitor mode** — `SENTINEL_MODE=monitor` (or `Sentinel(mode="monitor")`) logs the
  would-be verdict and **never blocks** — the kill switch still works. Deploy in front of
  a live agent, watch, build trust, then flip to enforce. (Try `SENTINEL_MODE=monitor sentinel demo`.)
- **Dashboard auth** — set `SENTINEL_API_TOKEN` (or let `sentinel serve` generate one);
  mutating endpoints (kill / policy / approve) then require `Authorization: Bearer …`.
- **Human-in-the-loop** — a `require_approval` call is parked; approve it from the
  dashboard or `sentinel approve <id>`, and the next identical call runs exactly once.
- **Interop** — `sentinel export --format otel` emits OpenTelemetry GenAI spans
  (`gen_ai.*`) for Langfuse / Datadog / any OTel backend.
- **Compliance** — `sentinel compliance --all` maps Sentinel to EU AI Act, GDPR, NIST AI
  RMF, ISO 42001, Colorado AI Act, and SEC/FINRA with honest full/partial/none coverage
  ([COMPLIANCE.md](COMPLIANCE.md)); `sentinel export --format art12` produces an EU AI Act
  Article 12 record-keeping report.
- **Housekeeping** — `sentinel gc` purges stale approvals / rate-limit state (never the audit log).
- **Overhead** — ~0.4 ms per guarded call on a dev laptop (policy + detector + two durable
  audit writes), well under the 20 ms target. Reproduce: `python examples/benchmark.py`.

## Documents

| File | What |
|---|---|
| [RESEARCH.md](RESEARCH.md) | Market & competitive research, wedge recommendation |
| [PRD.md](PRD.md) | Product requirements for this MVP |
| [ARCHITECTURE.md](ARCHITECTURE.md) | Components, data flow, threat model |
| [DECISIONS.md](DECISIONS.md) | Decision log |
| [INTEGRATIONS.md](INTEGRATIONS.md) | Add Sentinel to any framework (LangChain, OpenAI, CrewAI, MCP, …) |
| [LAUNCH.md](LAUNCH.md) | The honest go-to-market plan + ready-to-post launch assets (`launch/`, `site/`) |
| [DEMO.md](DEMO.md) | How to run the end-to-end demo |
| [ROADMAP.md](ROADMAP.md) | What's next, and the known-limitation → feature map |
| [SECURITY.md](SECURITY.md) | Design posture, self-check, known limitations |
| [COMPLIANCE.md](COMPLIANCE.md) | Mapping to AI/data law (EU AI Act, GDPR, NIST, ISO 42001, Colorado, SEC/FINRA) |
| [CHANGELOG.md](CHANGELOG.md) | Release notes |

## License

Apache-2.0.
