Metadata-Version: 2.4
Name: sentinel-kernel
Version: 0.1.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 :: 3 - Alpha
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>=0.2; extra == 'langchain'
Requires-Dist: langgraph>=0.1; extra == 'langchain'
Provides-Extra: opa
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
Requires-Dist: opentelemetry-exporter-otlp>=1.20; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29; extra == 'postgres'
Requires-Dist: psycopg2-binary>=2.9; extra == 'postgres'
Description-Content-Type: text/markdown

# sentinel-kernel

**The EU-sovereign decision record layer for AI agents.**

Sentinel wraps agent execution, evaluates policy rules in-process, and writes append-only decision traces to local storage. It runs fully offline, has zero hard dependencies, and does not communicate with any external service. You own your data.

> **Status: Alpha.** Core trace schema and storage interfaces are stabilising. Not yet production-ready. API may change.

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
[![EU AI Act](https://img.shields.io/badge/EU%20AI%20Act-Art.%2012%20Logging-003399)](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32024R1689)
[![Schema](https://img.shields.io/badge/Schema-v1.0.0--draft-orange)](docs/schema.md)
[![Governance](https://img.shields.io/badge/Governance-LF%20Europe%20intended-lightgrey)](https://linuxfoundation.eu)

---

## What Sentinel is

- Wraps agent function calls with a thin decorator — sync and async — without modifying agent logic
- Evaluates policy rules in-process before execution, producing a structured `PolicyResult` per call
- Records structured, SHA-256-hashed decision traces capturing inputs, outputs, policy evaluation, latency, and data residency metadata
- Works fully offline and in air-gapped environments — no network calls, no external dependencies
- Ships with pluggable storage: SQLite for structured querying, filesystem NDJSON for append-only log pipelines, or a custom backend via the `StorageBackend` interface
- Has no dependency on any cloud provider, model vendor, or hosted control plane

---

## What Sentinel is not

- Not an LLM gateway or proxy — it does not sit between your application and a model API
- Not a content moderation layer — it does not inspect or filter model outputs
- Not a hosted control plane — there is no Sentinel-managed cloud, dashboard, or SaaS offering
- Not tied to a model vendor — works with any model, any inference provider, or no model at all
- Not a SIEM or observability replacement — it produces decision records, not metrics, traces, or log aggregation

---

## Why it exists

The EU AI Act (Regulation 2024/1689) requires operators of high-risk AI systems to maintain logs of automated decisions, with records sufficient to reconstruct what happened and why. Article 12 obligations apply from 2 August 2026. Most existing logging approaches — cloud-hosted observability platforms, LLM gateway logs, third-party audit services — place decision records under foreign jurisdiction or create dependencies that conflict with data sovereignty requirements.

The US CLOUD Act means US-headquartered providers can be compelled to disclose data stored anywhere in the world. For AI systems deployed in regulated EU sectors — financial services, healthcare, critical infrastructure, public administration — this creates jurisdictional risk that cannot be mitigated by contractual means alone.

Sentinel is designed for deployments where the record of what an AI agent decided must remain within a controlled, auditable boundary. It is built for teams who need to demonstrate compliance without depending on a third-party platform to hold that evidence.

---

## Quick start

```bash
git clone https://github.com/sebastianweiss83/sentinel-kernel.git
cd sentinel-kernel
pip install -e .
```

```python
from sentinel import Sentinel
from sentinel.storage import SQLiteStorage

sentinel = Sentinel(
    storage=SQLiteStorage(":memory:"),
    project="demo",
)

@sentinel.trace
async def approve_discount(deal_id: str, amount: float) -> dict:
    return {"decision": "approve", "amount": amount}

# Every call produces a structured decision trace
result = await approve_discount("deal-42", amount=5000.0)

# Query traces
traces = sentinel.query(project="demo", limit=5)
print(traces[0].to_json())
```

Example trace output:

```json
{
  "schema_version": "1.0.0",
  "trace_id": "3f2a1b4c-8e7d-4f6a-9c2b-1d0e5f3a8b7c",
  "parent_trace_id": null,
  "project": "demo",
  "agent": "approve_discount",
  "started_at": "2026-04-02T09:14:32.104Z",
  "completed_at": "2026-04-02T09:14:32.107Z",
  "latency_ms": 3,
  "inputs_hash": "a4c2e1f8b3d790ef12c4a5b6d7e8f901...",
  "inputs": {
    "deal_id": "deal-42",
    "amount": 5000.0
  },
  "output": {
    "decision": "approve",
    "amount": 5000.0
  },
  "output_hash": "f7b1d3c9a2e4561b8c0d3e2f1a4b5c6d...",
  "model": {
    "provider": null,
    "name": null,
    "version": null,
    "tokens_input": null,
    "tokens_output": null
  },
  "policy": null,
  "human_override": null,
  "sovereignty": {
    "data_residency": "local",
    "sovereign_scope": "local",
    "storage_backend": "sqlite"
  },
  "tags": {},
  "precedent_trace_ids": []
}
```

---

## Architecture

```
Your agent function
        |
        v
+-------------------+
|  @sentinel.trace  |  <- Interceptor: captures inputs, timing, context
+--------+----------+
         |
         v
+-------------------+
|  Policy evaluator |  <- In-process: NullPolicy / SimpleRule / LocalRego (OPA)
+--------+----------+
         |
         v
+-------------------+
|  DecisionTrace    |  <- Serialized, hashed, sovereignty metadata attached
+--------+----------+
         |
         v
+-------------------+
|  StorageBackend   |  <- SQLite / Filesystem NDJSON / custom implementation
+-------------------+
```

**Interceptor** — The `@sentinel.trace` decorator wraps any sync or async function. It captures inputs, records start and end timestamps, computes SHA-256 hashes of inputs and outputs, and passes execution context to the policy evaluator before calling the underlying function.

**Policy evaluation** — Runs in-process before the agent function executes. Three evaluators ship with the package: `NullPolicyEvaluator` (default, always returns `NOT_EVALUATED`), `SimpleRuleEvaluator` (accepts Python callables), and `LocalRegoEvaluator` (shells out to a local OPA binary — no network call). Results are one of `ALLOW`, `DENY`, `EXCEPTION`, or `NOT_EVALUATED`.

**Trace serialization** — `DecisionTrace` is a dataclass with `to_dict()`, `to_json()`, and `from_dict()`. The schema includes sovereignty metadata (`DataResidency`, `sovereign_scope`, `storage_backend`) and supports human override records (`HumanOverride`).

**Storage backend** — `StorageBackend` is an abstract interface. `SQLiteStorage` provides full CRUD with indexing. `FilesystemStorage` appends NDJSON with daily log rotation. Custom backends implement the interface.

**Optional extras** — LangChain integration, PostgreSQL storage, and OpenTelemetry export are planned as optional extras and will not add to the zero-dependency core. See [docs/landscape.md](docs/landscape.md) for how Sentinel relates to the broader LLMOps and agent ecosystem.

---

## Current status

| Component | Status |
|---|---|
| `@sentinel.trace` decorator | Implemented — sync and async |
| `DecisionTrace` schema | Implemented — v1.0.0 draft |
| SQLite storage | Implemented |
| Filesystem / NDJSON storage | Implemented |
| `StorageBackend` interface | Implemented |
| `SimpleRuleEvaluator` | Implemented |
| `LocalRegoEvaluator` (OPA) | Implemented — requires OPA binary |
| Human override model | Implemented |
| LangChain integration | Planned (v0.3) |
| PostgreSQL storage | Planned |
| CLI (`sentinel` command) | Declared, not yet implemented |
| Test suite | 71 tests, 86% coverage |
| BSI IT-Grundschutz assessment | Planned (v1.0) |

---

## Repository structure

```
sentinel-kernel/
├── sentinel/
│   ├── __init__.py         # Public API: Sentinel, DecisionTrace, enums
│   ├── core/
│   │   ├── trace.py        # DecisionTrace, PolicyEvaluation, HumanOverride
│   │   └── tracer.py       # Sentinel class, @trace decorator, span(), query()
│   ├── policy/
│   │   └── evaluator.py    # NullPolicy, SimpleRule, LocalRego evaluators
│   └── storage/
│       ├── base.py         # StorageBackend abstract interface
│       ├── sqlite.py       # SQLiteStorage
│       └── filesystem.py   # FilesystemStorage (NDJSON)
├── docs/                   # Schema, architecture, compliance, quickstart
├── examples/               # Runnable examples
├── tests/                  # Test suite
├── VISION.md               # Project direction and governance intent
├── GOVERNANCE.md           # Decision-making, roles, foundation path
├── CONTRIBUTING.md         # Contribution guide
└── CHANGELOG.md            # Version history
```

---

## Contributing

Sentinel is early-stage. Useful contributions right now: test coverage, schema feedback, storage backend implementations, and compliance use case documentation. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Breaking changes to `DecisionTrace` and `StorageBackend` require an RFC.

---

## License and governance

Sentinel is released under the [Apache 2.0 License](LICENSE).

Sentinel is designed for foundation stewardship under Linux Foundation Europe. Formal engagement is planned alongside v1.0. Until then, governance decisions are made transparently through the RFC process. See [GOVERNANCE.md](GOVERNANCE.md) for the full governance model, decision-making process, and contributor path.
