Metadata-Version: 2.4
Name: sentinel-kernel
Version: 3.0.7
Summary: Sovereign decision tracing for any autonomous system. LLMs, ML classifiers, rule engines, and robotic systems. EU AI Act compliant. Air-gapped capable. Apache 2.0.
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-governance,air-gapped,audit-trail,autonomous-systems,bsi,compliance,decision-tracing,eu-ai-act,llm,machine-learning,manifesto-as-code,post-quantum,robotics,rule-engine,sovereignty
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Legal Industry
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
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.25; extra == 'anthropic'
Provides-Extra: autogen
Requires-Dist: pyautogen>=0.2; extra == 'autogen'
Provides-Extra: crewai
Requires-Dist: crewai>=0.1; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: django>=4.2; extra == 'dev'
Requires-Dist: hatch>=1.9; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: ipywidgets>=8.0; extra == 'dev'
Requires-Dist: langchain-core>=0.1; extra == 'dev'
Requires-Dist: langfuse>=2.0; extra == 'dev'
Requires-Dist: mypy>=1.9; extra == 'dev'
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20; extra == 'dev'
Requires-Dist: opentelemetry-sdk>=1.20; extra == 'dev'
Requires-Dist: prometheus-client>=0.19; extra == 'dev'
Requires-Dist: psycopg2-binary>=2.9; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: rich>=13.0; extra == 'dev'
Requires-Dist: ruff>=0.3; extra == 'dev'
Requires-Dist: starlette>=0.30; extra == 'dev'
Provides-Extra: django
Requires-Dist: django>=4.2; extra == 'django'
Provides-Extra: fastapi
Requires-Dist: starlette>=0.30; extra == 'fastapi'
Provides-Extra: haystack
Requires-Dist: haystack-ai>=2.0; extra == 'haystack'
Provides-Extra: jupyter
Requires-Dist: ipython>=8.0; extra == 'jupyter'
Requires-Dist: ipywidgets>=8.0; extra == 'jupyter'
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'
Provides-Extra: pqc
Requires-Dist: oqs-python>=0.8; extra == 'pqc'
Provides-Extra: prometheus
Requires-Dist: prometheus-client>=0.19; extra == 'prometheus'
Description-Content-Type: text/markdown

# sentinel-kernel

**The Sovereign Decision Kernel.**

Sentinel sits between your business logic and any autonomous decision
system. It records every decision — sovereign, tamper-resistant,
append-only — and enforces what is allowed to be decided.

Works with LLMs, ML classifiers, rule engines, and robotic systems.
If it decides, Sentinel records it.

Three layers:

- **Trace** — every decision recorded, sovereign, tamper-resistant
- **Govern** — what may be decided, policy-as-code, kill switch
- **Route** *(v4.0)* — which system decides what, based on sovereignty
  policy and data classification

No vendor lock-in. No US CLOUD Act. No deployment strategists.
Apache 2.0, permanently.

EU AI Act Annex III enforcement: **2 August 2026**. Sentinel turns that
legal requirement into a technical fact — in five minutes, with zero
cloud dependencies, in any environment including air-gapped.

→ Full vision: [docs/vision.md](docs/vision.md) · Full roadmap: [docs/roadmap.md](docs/roadmap.md)

<!-- SYNC_ALL_README_START -->
[![PyPI](https://img.shields.io/pypi/v/sentinel-kernel)](https://pypi.org/project/sentinel-kernel/)
[![Version](https://img.shields.io/badge/version-v3.0.7-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-615%20passing-brightgreen)](https://github.com/sebastianweiss83/sentinel-kernel/actions)
[![Coverage](https://img.shields.io/badge/coverage-99%25-brightgreen)](https://github.com/sebastianweiss83/sentinel-kernel/actions)
[![Status](https://img.shields.io/badge/status-production%2Fstable-brightgreen)](CHANGELOG.md)
[![EU AI Act](https://img.shields.io/badge/EU%20AI%20Act-Art.%2012%2F13%2F14%2F17-green)](docs/eu-ai-act.md)
<!-- SYNC_ALL_README_END -->

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

## Quick demo

```bash
# macOS (recommended)
brew install pipx && pipx install sentinel-kernel
sentinel demo

# Linux / Docker / CI
pip install sentinel-kernel
sentinel demo

# Alternative (always works)
python3 -m pip install sentinel-kernel
python3 -m sentinel demo
```

---

## 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
# macOS (recommended — avoids PEP 668 "externally-managed-environment")
brew install pipx
pipx install sentinel-kernel
sentinel demo

# Linux / Docker / CI
pip install sentinel-kernel
sentinel demo

# Alternative (always works)
python3 -m pip install sentinel-kernel
python3 -m sentinel demo
```

`python3 -m sentinel` is equivalent to the `sentinel` entry point and always
works, even on systems where the bin directory is not on PATH.

## 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 | Cloud observability tools | Proprietary 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, your ML model, or your rule engine — it does not care which technology makes the decision. It wraps any Python function and produces a legally-valid, portable, sovereign record of every decision it makes.

---

## 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,
)
# For PostgreSQL: from sentinel.storage.postgres import PostgresStorage
```

**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

| Phase | Status | What |
|---|---|---|
| **Trace + Govern** | ✓ v3.0 | Sovereign traces, policy-as-code, kill switch |
| **Certify** | → 2026 | BSI IT-Grundschutz, LF Europe |
| **Route** | → v4.0 | Sovereign model router |
| **Ecosystem** | 2027+ | EU build pipeline, multi-language |

Full phase detail, including the SovereignRouter design and the
market thesis, lives in [docs/roadmap.md](docs/roadmap.md).

### Version history

| Version | Status | Milestone |
|---------|--------|-----------|
| **v1.0** | ✓ shipped | Core production baseline |
| **v1.5** | ✓ shipped | DORA, NIS2, VS-NfD compliance |
| **v2.0** | ✓ shipped | Production stable, BSI ready |
| **v2.1** | ✓ shipped | BudgetTracker, attestations, CrewAI, AutoGen |
| **v2.2** | ✓ shipped | ML-DSA-65 quantum-safe signing |
| **v2.3** | ✓ shipped | LangFuse sovereignty panel |
| **v2.4** | ✓ shipped | Rust RFC-001 implementation |
| **v3.0** | ✓ shipped | API frozen, BSI pre-engagement package |
| **v3.1** | Q3 2026 | LF Europe application |
| **v3.2** | Q4 2026 | BSI IT-Grundschutz assessment |
| **v4.0** | 2026-27 | SovereignRouter |

## EU AI Act compliance

| Article | Requirement | Sentinel |
|---------|------------|---------|
| Art. 12 | Auto logging | ✓ Full — automated |
| Art. 13 | Transparency | ✓ Full — automated |
| Art. 14 | Human oversight | ✓ Full — kill switch |
| Art. 9  | Risk management | ~ Partial — policy traces |
| Art. 11 | Technical docs | → Human action — Annex IV required |
| Art. 17 | Quality mgmt | ✓ Full — continuous record |
| Art. 16 | Provider obligations | ~ Partial — logging covered |
| Art. 26 | Deployer obligations | ~ Partial — logging + oversight |
| Art. 10 | Data governance | → Human action |
| Art. 15 | Accuracy | → Human action |
| Art. 72 | GPAI (if applicable) | ~ Conditional |

**Sentinel never overclaims.** Articles requiring human action are
clearly marked. Partial articles are those where Sentinel produces
the evidence but an organisational deliverable must still be written.

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 business logic
        │
        ▼
┌─────────────────────────────────────────┐
│           SENTINEL KERNEL               │
│                                         │
│  ┌───────────────┐  ┌─────────────────┐ │
│  │    GOVERN ✓   │  │   ROUTE → v4.0  │ │
│  │  Policy-code  │  │  Which model?   │ │
│  │  Kill switch  │  │  Sovereignty?   │ │
│  │  Preflight    │  │  Data class?    │ │
│  └───────────────┘  └─────────────────┘ │
│                                         │
│  ┌─────────────────────────────────┐    │
│  │          TRACE ✓                │    │
│  │  Sovereign · Tamper-resistant   │    │
│  └─────────────────────────────────┘    │
└─────────────────────────────────────────┘
        │
        ▼
  DECISION LAYER (your choice)
  LLMs · ML classifiers · Rule engines · Robotic systems
  Switch anytime. No lock-in.
        │
        ▼
  SOVEREIGN STORAGE
  SQLite · PostgreSQL · NDJSON
  Your infrastructure. Always.
```

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

## Why it works for any autonomous system

The EU AI Act does not regulate language models. It regulates decisions.
Article 12 requires automatic, tamper-resistant logging of every decision
made by a high-risk system — regardless of the technology underneath.

An LLM, a gradient-boosted classifier, a rule engine, an industrial
robot: if it makes a high-risk decision, it needs a sovereign decision
record.

```python
# Works with any decision function
@sentinel.trace
async def my_decision(context: dict) -> dict:
    return await any_system.decide(context)
    # LLM, ML model, rule engine, robot control system
    # Sentinel doesn't care. It records the decision.
```

## Why not Palantir AIP

Palantir AIP costs €5–20M per year. It is US-incorporated (CLOUD Act
applies to all your data). It requires deployment strategists. It is
proprietary.

When LLMs guide their own integration — and that is already happening —
the deployment-strategist model collapses. What survives is the trusted
kernel underneath: policy, audit trail, model router, sovereignty proof.

Sentinel is that kernel. Open source. EU sovereign. Self-service.
Apache 2.0, permanently. The full argument is in [docs/vision.md](docs/vision.md).

---

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

---

---

If Sentinel helps you meet EU AI Act requirements, consider giving
it a ⭐ on GitHub — it helps others find the project.

---

## 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/vision.md](docs/vision.md) — the Sovereign Decision Kernel, in full
- [docs/roadmap.md](docs/roadmap.md) — three phases, Router design
- [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 7 policy templates
- [docs/landscape.md](docs/landscape.md) — how Sentinel relates to LLMOps ecosystem
- [docs/architecture.md](docs/architecture.md) — detailed architecture
- [docs/releasing.md](docs/releasing.md) — release runbook
- [CLAUDE_MEGA_PROMPT.md](CLAUDE_MEGA_PROMPT.md) — persistent Claude Code reference
- [VISION.md](VISION.md) — strategic vision
- [ROADMAP.md](ROADMAP.md) — detailed milestones
- [GOVERNANCE.md](GOVERNANCE.md) — governance model
- [CHANGELOG.md](CHANGELOG.md) — version history
