Metadata-Version: 2.4
Name: sentinel-kernel
Version: 1.0.0
Summary: EU-sovereign decision record layer for AI agents.
Project-URL: Homepage, https://github.com/sebastianweiss83/sentinel-kernel
Project-URL: Documentation, https://github.com/sebastianweiss83/sentinel-kernel/tree/main/docs
Project-URL: Repository, https://github.com/sebastianweiss83/sentinel-kernel
Project-URL: Issues, https://github.com/sebastianweiss83/sentinel-kernel/issues
Project-URL: Changelog, https://github.com/sebastianweiss83/sentinel-kernel/blob/main/CHANGELOG.md
License: Apache License
        Version 2.0, January 2004
        http://www.apache.org/licenses/
        
        TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
        
        1. Definitions.
        
        "License" shall mean the terms and conditions for use, reproduction,
        and distribution as defined by Sections 1 through 9 of this document.
        
        "Licensor" shall mean the copyright owner or entity authorized by
        the copyright owner that is granting the License.
        
        "Legal Entity" shall mean the union of the acting entity and all
        other entities that control, are controlled by, or are under common
        control with that entity.
        
        "You" (or "Your") shall mean an individual or Legal Entity
        exercising permissions granted by this License.
        
        "Source" form shall mean the preferred form for making modifications,
        including but not limited to software source code, documentation
        source, and configuration files.
        
        "Object" form shall mean any form resulting from mechanical
        transformation or translation of a Source form, including but
        not limited to compiled object code, generated documentation,
        and conversions to other media types.
        
        "Work" shall mean the work of authorship made available under
        the License, as indicated by a copyright notice that is included in
        or attached to the work.
        
        "Derivative Works" shall mean any work that is based on the Work,
        for which the editorial revisions, annotations, elaborations, or
        other modifications represent, as a whole, an original work of
        authorship.
        
        "Contribution" shall mean any work of authorship submitted to the
        Licensor for inclusion in the Work by the copyright owner or by
        an individual or Legal Entity authorized to submit on behalf of
        the copyright owner.
        
        "Contributor" shall mean Licensor and any Legal Entity on behalf of
        whom a Contribution has been received by the Licensor and included
        within the Work.
        
        2. Grant of Copyright License. Subject to the terms and conditions of
        this License, each Contributor hereby grants to You a perpetual,
        worldwide, non-exclusive, no-charge, royalty-free, irrevocable
        copyright license to reproduce, prepare Derivative Works of,
        publicly display, publicly perform, sublicense, and distribute the
        Work and such Derivative Works in Source or Object form.
        
        3. Grant of Patent License. Subject to the terms and conditions of
        this License, each Contributor hereby grants to You a perpetual,
        worldwide, non-exclusive, no-charge, royalty-free, irrevocable
        (except as stated in this section) patent license to make, have made,
        use, offer to sell, sell, import, and otherwise transfer the Work.
        
        4. Redistribution. You may reproduce and distribute copies of the
        Work or Derivative Works thereof in any medium, with or without
        modifications, and in Source or Object form, provided that You
        meet the following conditions:
        
        (a) You must give any other recipients of the Work or Derivative
        Works a copy of this License; and
        
        (b) You must cause any modified files to carry prominent notices
        stating that You changed the files; and
        
        (c) You must retain, in the Source form of any Derivative Works
        that You distribute, all copyright, patent, trademark, and
        attribution notices from the Source form of the Work; and
        
        (d) If the Work includes a "NOTICE" text file, you must include a
        readable copy of the attribution notices contained within such
        NOTICE file, in at least one of the following places: within a
        NOTICE text file distributed as part of the Derivative Works;
        within the Source form or documentation; or within a display
        generated by the Derivative Works, if and where such third-party
        notices normally appear.
        
        5. Submission of Contributions. Unless You explicitly state otherwise,
        any Contribution submitted for inclusion in the Work shall be under
        the terms and conditions of this License.
        
        6. Trademarks. This License does not grant permission to use the trade
        names, trademarks, service marks, or product names of the Licensor.
        
        7. Disclaimer of Warranty. UNLESS REQUIRED BY APPLICABLE LAW OR
        AGREED TO IN WRITING, LICENSOR PROVIDES THE WORK ON AN "AS IS"
        BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
        
        8. Limitation of Liability. IN NO EVENT SHALL ANY CONTRIBUTOR BE
        LIABLE FOR ANY DAMAGES ARISING FROM USE OF THE WORK.
        
        9. Accepting Warranty or Additional Liability. You may choose to
        offer warranty or liability obligations consistent with this License.
        
        Copyright 2026 Sebastian Weiss and Sentinel Contributors
        
        Licensed under the Apache License, Version 2.0 (the "License");
        you may not use this file except in compliance with the License.
        You may obtain a copy of the License at
        
            http://www.apache.org/licenses/LICENSE-2.0
License-File: LICENSE
Keywords: AI,EU,GDPR,LLM,agents,audit,decision-trace,middleware,sovereignty
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security
Requires-Python: >=3.11
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.25; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: hatch>=1.9; extra == 'dev'
Requires-Dist: mypy>=1.9; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.3; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1; extra == 'langchain'
Provides-Extra: langfuse
Requires-Dist: langfuse>=2.0; extra == 'langfuse'
Provides-Extra: opa
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Provides-Extra: otel
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
Provides-Extra: postgres
Requires-Dist: psycopg2-binary>=2.9; extra == 'postgres'
Description-Content-Type: text/markdown

# sentinel-kernel

**AI decisions. Recorded. Sovereign. Auditable.**

Every AI agent makes decisions. From **2 August 2026**, EU high-risk AI systems must prove it — automatically, tamper-resistantly, under EU law. Sentinel makes that possible in five minutes, with zero cloud dependencies, in any environment including air-gapped.

[![PyPI](https://img.shields.io/pypi/v/sentinel-kernel)](https://pypi.org/project/sentinel-kernel/)
[![Version](https://img.shields.io/badge/version-v0.9.1-blue)](CHANGELOG.md)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](https://www.apache.org/licenses/LICENSE-2.0)
[![Tests](https://img.shields.io/badge/tests-183%20passing-brightgreen)](https://github.com/sebastianweiss83/sentinel-kernel/actions)
[![Status](https://img.shields.io/badge/status-beta-orange)](CHANGELOG.md)
[![EU AI Act](https://img.shields.io/badge/EU%20AI%20Act-Art.%2012%2F13%2F14%2F17-green)](docs/eu-ai-act.md)

**Live preview:** https://sebastianweiss83.github.io/sentinel-kernel/
**Get started in 2 minutes:** [docs/getting-started.md](docs/getting-started.md)

---

## Quick demo — full stack in one command

```bash
git clone https://github.com/sebastianweiss83/sentinel-kernel
cd sentinel-kernel/demo
docker compose up --build
```

Then open **http://localhost:3001** (Grafana, `admin` / `sentinel`).

The demo runs a realistic EU defence contractor scenario — policy
evaluation, kill switch (Art. 14), document analysis, sovereignty
scan — and streams live traces to Grafana. See
[demo/README.md](demo/README.md) for what to look at.

## Install

```bash
pip install sentinel-kernel
```

## Five minutes to your first sovereign trace

```python
from sentinel import Sentinel

sentinel = Sentinel()  # local storage, zero config, no network

@sentinel.trace
async def approve_request(payload: dict) -> dict:
    # your existing agent logic — unchanged
    return await your_agent.run(payload)

result = await approve_request({"action": "approve", "amount": 50000})
```

That's it. Every call now produces a tamper-resistant decision record:

```json
{
  "trace_id": "01hx7k9m2n3p4q5r6s7t8u9v0w",
  "timestamp": "2026-04-01T14:23:41.234Z",
  "agent": "approve_request",
  "model": "mistral/large-2",
  "policy_result": "ALLOW",
  "inputs_hash": "sha256:a3f8c2d19e4b67f0c1a5d8e2b9c3f4a7",
  "output": {"decision": "approved"},
  "sovereign_scope": "EU",
  "data_residency": "local",
  "schema_version": "1.0.0"
}
```

Stored locally. No cloud account. No API key. No network call.

---

## With policy evaluation

```python
from sentinel import Sentinel, DataResidency
from sentinel.policy import SimpleRuleEvaluator
from sentinel.storage import FilesystemStorage

def within_threshold(ctx: dict) -> tuple[bool, str | None]:
    if ctx.get("amount", 0) > ctx.get("agent_threshold", 0):
        return False, "amount_exceeds_threshold"
    return True, None

# works fully offline — classified environments, air-gapped networks
sentinel = Sentinel(
    storage=FilesystemStorage("/mnt/traces"),
    policy_evaluator=SimpleRuleEvaluator({
        "policies/procurement.py": within_threshold,
    }),
    sovereign_scope="EU",
    data_residency=DataResidency.EU_DE,
)

@sentinel.trace(policy="policies/procurement.py")
async def evaluate_procurement(ctx: dict) -> dict:
    return await agent.run(ctx)
```

For OPA/Rego policies:

```python
from sentinel import Sentinel
from sentinel.policy import LocalRegoEvaluator

sentinel = Sentinel(
    policy_evaluator=LocalRegoEvaluator(opa_binary="opa"),
    # OPA runs in-process — no network, no OPA server
)

@sentinel.trace(policy="policies/procurement.rego")
async def evaluate_procurement(ctx: dict) -> dict:
    return await agent.run(ctx)
```

---

## What Sentinel does. What it doesn't.

| | Sentinel | LLM observability tools | Proprietary AI platforms |
|---|---|---|---|
| Sovereign decision records | ✓ | — | Vendor-jurisdicted |
| In-process policy evaluation | ✓ | — | — |
| Air-gapped operation | ✓ | — | — |
| BSI IT-Grundschutz path | ✓ | — | — |
| EU AI Act Art. 12 compliance | ✓ | — | Partial |
| Zero hard dependencies | ✓ | — | — |
| Apache 2.0 permanently | ✓ | Varies | — |
| US CLOUD Act exposure | **None** | Varies | **Unconditional** |

Sentinel is not an observability tool. It is not a content filter. It does not replace your LLM or your agent framework. It wraps them — and produces a legally-valid, portable, sovereign record of every decision they make.

---

## Deployment

**Local / development**
```python
sentinel = Sentinel()  # SQLite, no config
```

**On-premise enterprise**
```python
from sentinel import Sentinel, DataResidency
from sentinel.storage import SQLiteStorage

sentinel = Sentinel(
    storage=SQLiteStorage("/var/lib/sentinel/traces.db"),
    sovereign_scope="EU",
    data_residency=DataResidency.EU_DE,
)
# PostgreSQL storage planned for v0.2
```

**Air-gapped / classified**
```python
from sentinel import Sentinel, DataResidency
from sentinel.storage import FilesystemStorage

sentinel = Sentinel(
    storage=FilesystemStorage("/mnt/traces"),
    data_residency=DataResidency.AIR_GAPPED,
)
# zero network connectivity required
# traces written as NDJSON, one file per day
```

---

## Why sovereignty matters

The US CLOUD Act (18 U.S.C. § 2713) requires US-incorporated companies to produce data stored anywhere in the world on valid legal process. This applies to EU data centres operated by US companies. No contract eliminates it.

EU AI Act Article 12 mandates automatic, tamper-resistant logging for high-risk AI systems from **2 August 2026**. Decision logs that are simultaneously accessible to US authorities do not satisfy this requirement from EU jurisdiction.

Sentinel's critical path — interceptor, policy evaluation, trace emission, storage — contains no US-owned components. This is architectural. Not a configuration option.

---

## Roadmap

| Version | Status | Milestone |
|---|---|---|
| **v0.1**   | ✓ shipped | Kernel, in-process policy eval, SQLite + Filesystem storage |
| **v0.1.1** | ✓ shipped | Kill switch (EU AI Act Art. 14 halt mechanism) |
| **v0.2**   | ✓ shipped | PostgreSQL storage backend (optional extra) |
| **v0.3**   | ✓ shipped | LangChain callback handler + OpenTelemetry export + LangFuse enrichment |
| **v0.4**   | ✓ shipped | Air-gapped validation suite with network blocking |
| **v0.5**   | ✓ shipped | Sovereignty scanner (runtime, CI/CD, infrastructure) |
| **v0.6**   | ✓ shipped | Manifesto-as-code (`SentinelManifesto`) |
| **v0.7**   | ✓ shipped | EU AI Act compliance checker + diff report |
| **v0.8**   | ✓ shipped | Demo environment (Docker Compose + Grafana dashboard) |
| **v0.9**   | ✓ shipped | Sovereignty dashboard (terminal + self-contained HTML) |
| **v1.0**   | Q4 2026  | BSI IT-Grundschutz assessment — certified sovereign |
| **v1.1**   | Q1 2027  | VS-NfD classified deployment profile |

## What's in v0.9

v0.9 ships the complete **sovereignty platform**: the decision record
kernel (v0.1–v0.4) plus everything a regulated team needs to evaluate,
declare, and verify sovereignty end-to-end.

- **`sentinel scan`** — runtime, CI/CD, and infrastructure scanners
  that classify every dependency by parent company and jurisdiction.
- **`SentinelManifesto`** — declare sovereignty requirements as a
  Python class; run it against reality; get a structured report
  with gaps, acknowledged gaps, and migration plans.
- **`EUAIActChecker`** — automated EU AI Act compliance check with
  honest gap reporting. Distinguishes machine-checkable articles
  (12, 13, 14, 17) from organisational obligations (10, 11, 15).
- **`sentinel report`** — generate a self-contained HTML sovereignty
  report suitable for regulatory review. No CDN, no external
  resources — air-gapped safe by construction.
- **`sentinel dashboard`** — live terminal dashboard showing
  decision traces, policy results, sovereignty score, and kill
  switch state. Zero dependencies.
- **Demo package** — `demo/` with Docker Compose (OTel collector,
  Prometheus, Grafana, self-hosted LangFuse) running three realistic
  industry scenarios end-to-end.
- **RFC-001** — `SovereigntyManifest` specification, the first
  step toward a cross-project standard.

---

## EU AI Act compliance

| Article | Requirement | Sentinel |
|---|---|---|
| Art. 9 | Risk management | Policy eval recorded in every trace |
| Art. 12 | Automatic tamper-resistant logging | Every decision produces a trace automatically |
| Art. 13 | Transparency to deployers | Policy name, version, result in every trace |
| Art. 14 | Human oversight + kill switch | Override mechanism → linked immutable trace |
| Art. 17 | Quality management | Continuous tamper-resistant record |

Enforcement for Annex III high-risk AI: **2 August 2026**. Penalties up to €15M or 3% of global annual turnover.

Full mapping: [docs/eu-ai-act.md](docs/eu-ai-act.md)

---

## Architecture

```
Your AI agents (any framework, any model)
         │
         ▼
  ┌─────────────────────┐
  │   Sentinel Kernel   │  ← wraps any agent call
  │                     │
  │  Interceptor        │  ← captures inputs, timing, context
  │  Policy Evaluator   │  ← in-process: Rego / Python / custom
  │  Trace Serializer   │  ← SHA-256 hashed, schema-versioned
  └──────────┬──────────┘
             │
    ┌────────┼────────┐
    ▼        ▼        ▼
 SQLite  PostgreSQL  Filesystem
                     (NDJSON, air-gapped)
```

**Critical path guarantees:**
- Zero hard dependencies
- Zero network calls at runtime
- Zero US CLOUD Act exposure
- Full offline / air-gapped operation

---

## Contributing

Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR.

Every integration must document its sovereignty posture. Schema changes require an RFC. Breaking changes to the trace format go through a 14-day comment period.

```bash
git clone https://github.com/sebastianweiss83/sentinel-kernel
cd sentinel-kernel
pip install -e ".[dev]"
pytest
```

---

## License

Apache 2.0. [Full text.](https://www.apache.org/licenses/LICENSE-2.0)

No BSL. No commercial-only features. No relicensing. Ever.

---

## Governance

Sentinel is pursuing stewardship under **Linux Foundation Europe**. Until confirmed, the project is maintained independently with all significant decisions made through the RFC process in GitHub Discussions.

---

## Documentation

- [docs/getting-started.md](docs/getting-started.md) — two-minute quickstart
- [docs/real-world-examples.md](docs/real-world-examples.md) — industry scenarios
- [docs/schema.md](docs/schema.md) — full trace schema reference
- [docs/eu-ai-act.md](docs/eu-ai-act.md) — Article 12/13/14/17 mapping
- [docs/integration-guide.md](docs/integration-guide.md) — framework integrations
- [docs/sovereignty.md](docs/sovereignty.md) — what sovereignty means
- [docs/ecosystem.md](docs/ecosystem.md) — sovereign AI project registry
- [docs/rfcs/RFC-001-sovereignty-manifest.md](docs/rfcs/RFC-001-sovereignty-manifest.md) — SovereigntyManifest spec (draft)
- [docs/bsi-profile.md](docs/bsi-profile.md) — BSI IT-Grundschutz profile
- [demo/README.md](demo/README.md) — Docker Compose demo environment
- [examples/](examples/) — 13 runnable examples and 5 policy templates
- [docs/landscape.md](docs/landscape.md) — how Sentinel relates to LLMOps ecosystem
- [docs/architecture.md](docs/architecture.md) — detailed architecture
- [docs/quickstart.md](docs/quickstart.md) — extended quickstart guide
- [VISION.md](VISION.md) — strategic vision
- [ROADMAP.md](ROADMAP.md) — detailed milestones
- [GOVERNANCE.md](GOVERNANCE.md) — governance model
- [CHANGELOG.md](CHANGELOG.md) — version history
