kl-kernel-logic 0.3.4

Lightweight deterministic execution substrate for governed operations.

KL Kernel Logic

KL Kernel Logic is a small deterministic execution substrate that separates the definition of an operation from its controlled execution. It does not orchestrate. It provides a clean, auditable execution core that higher-level systems can build on.

KL Kernel Logic separates the definition of an operation (Psi) from its execution (CAEL + Kernel).
It gives you a small execution core that can run both fully deterministic tasks and nondeterministic ones (for example AI calls) with a clear execution trace.

pip install kl-kernel-logic

from kl_kernel_logic import PsiDefinition, CAEL, CAELConfig

def uppercase(text: str) -> str:
    return text.upper()

psi = PsiDefinition(
    psi_type="text.uppercase",
    domain="text",
    effect="pure",
)

cael = CAEL(config=CAELConfig())
trace = cael.execute(psi=psi, task=uppercase, text="Hello KL")
print(trace.describe())

Table of Contents

• Overview
• Core Concepts
• Architecture
• Policy and Context
• Audit
• Repository Structure
• Installation
• Quick Start
• Foundations Examples
• Tests
• Theoretical Foundation
• Roadmap
• Contributing
• License
• Changelog

Overview

KL Kernel Logic provides a minimal grammar for defining operations (Psi) and executing them under explicit constraints (CAEL). It addresses a simple question:

How do we make execution transparent and auditable when deterministic and nondeterministic components are mixed?

KL does this by:

• defining operations in a declarative schema (Psi)
• transporting them via versioned envelopes
• executing them through a small kernel
• producing structured traces that other systems can inspect and store

The framework is domain-neutral. It does not impose business semantics. It is a binding layer for system builders and AI platform engineers.

Core Concepts

For complete API documentation, see: docs/api_reference.md

Psi

Psi describes the essence of an operation, independent of its technical implementation:

• psi_type: fully qualified operation identifier (for example "foundations.poisson_1d")
• domain: logical domain (for example "math", "io", "ai")
• effect: execution characteristic (for example "pure", "read", "io", "external", "ai")
• schema_version: Psi schema version (default "1.0")
• constraints: PsiConstraints for policy anchoring
• optional description, tags, metadata

Psi is immutable and serialisable via to_dict().

Effect classes

Effect classes describe the nature of the operation:

• pure - deterministic computation without side effects
• read - read-only operations
• io - filesystem or similar side effects
• external - network or remote calls
• ai - AI or model calls that may be nondeterministic

The default policy engine uses these effect classes but does not hard-code any domain logic.

PsiEnvelope

A PsiEnvelope is a versioned container around a Psi:

• carries the PsiDefinition
• adds envelope_id (UUID)
• adds creation timestamp
• optional metadata and signature

Envelopes give you a stable transport and audit container.

Kernel

The Kernel is the lowest-level execution engine. It:

• receives PsiDefinition, optional PsiEnvelope and a callable task
• executes the callable exactly once
• captures any exception as a string
• measures timing
• returns an ExecutionTrace

The kernel does not apply policies and does not orchestrate.

CAEL

The Controlled AI Execution Layer (CAEL):

• evaluates policies via a PolicyEngine
• builds or reuses a PsiEnvelope
• delegates execution to the Kernel
• records policy decisions in the resulting ExecutionTrace
• optionally classifies timeouts based on ExecutionContext.policy.timeout_seconds

CAEL is the main entry point for calling the kernel with governance hooks.

Architecture

For detailed architecture discussion, see: docs/kl-architecture.md

Textual overview:

Client / App / Orchestrator
            |
            v
+-------------------------------+
|        KL Kernel Logic        |
+-------------------------------+
       |                   |
       v                   v
   Psi Definition     Controlled Execution (CAEL)
         \               /
          \             /
           +-----------+
           |  Kernel   |
           +-----------+
                 |
                 v
        Task / Function / Model

Each run produces a trace that bundles:

• logical intent (Psi)
• transport metadata (Envelope)
• execution outcome and timing (ExecutionTrace)

Policy and Context

KL defines a small policy interface and a default policy engine.

from kl_kernel_logic import (
    PsiDefinition,
    CAEL, CAELConfig,
    ExecutionContext, ExecutionPolicy,
)
from kl_kernel_logic import PolicyViolationError

psi = PsiDefinition(
    psi_type="filesystem.write_example",
    domain="io",
    effect="io",
)

ctx = ExecutionContext(
    user_id="user_123",
    request_id="req_456",
    policy=ExecutionPolicy(
        allow_network=False,
        allow_filesystem=False,
        timeout_seconds=2.0,
    ),
)

cael = CAEL(config=CAELConfig())

try:
    trace = cael.execute(psi=psi, task=some_io_task, ctx=ctx)
except PolicyViolationError as exc:
    print(f"Blocked by {exc.policy_name}: {exc.reason}")

The built-in DefaultSafePolicyEngine:

• allows pure, read, ai
• denies io, external by default

Timeout classification is derived from ExecutionContext.policy.timeout_seconds and the measured runtime.

Audit

Audit is built on top of the execution trace.

from kl_kernel_logic import Kernel, PsiDefinition, PsiEnvelope
from kl_kernel_logic import build_audit_report

psi = PsiDefinition(
    psi_type="config.read",
    domain="config",
    effect="read",
)

envelope = PsiEnvelope(psi=psi, version="1.0")
kernel = Kernel()

trace = kernel.execute(psi=psi, task=lambda: "ok", envelope=envelope)
report = build_audit_report(trace)

print(report.describe())

Audit reports are simple, serialisable objects that include:

• run_id
• trace (from ExecutionTrace.describe())
• generated_at
• optional metadata

Repository Structure

src/kl_kernel_logic/
    __init__.py
    psi.py
    psi_envelope.py
    kernel.py
    cael.py
    execution_context.py
    policy.py
    audit.py
    examples_foundations/

tests/
docs/
    api_reference.md
    execution_theory_in_code.md
    kl-architecture.md
    foundational-execution-patterns.md
    roadmap.md

Core Modules

• psi.py - PsiDefinition and PsiConstraints
• psi_envelope.py - versioned envelope
• kernel.py - execution kernel and ExecutionTrace
• cael.py - CAEL wrapper and CAELConfig
• execution_context.py - ExecutionContext and ExecutionPolicy
• policy.py - PolicyEngine, PolicyDecision, DefaultSafePolicyEngine
• audit.py - AuditReport and builder
• examples_foundations - deterministic reference operations

Documentation

• api_reference.md - Complete API reference for 0.3.x
• execution_theory_in_code.md - Theory to code mapping
• kl-architecture.md - Architecture overview
• foundational-execution-patterns.md - Foundational execution patterns guide
• roadmap.md - Development roadmap

Installation

From PyPI

pip install kl-kernel-logic

From source

git clone https://github.com/lukaspfisterch/kl-kernel-logic.git
cd kl-kernel-logic

python -m venv .venv
# Activate venv as usual

pip install -e .

Quick Start

Two Execution Modes

KL provides two execution modes:

1. CAEL (Recommended for Production)

Use CAEL when you need:

• Policy evaluation and enforcement
• User context and request tracking
• Production-grade execution with governance

from kl_kernel_logic import CAEL, CAELConfig, PsiDefinition, ExecutionContext, ExecutionPolicy

def add(a: int, b: int) -> int:
    return a + b

psi = PsiDefinition(
    psi_type="math.add",
    domain="math",
    effect="pure",
)

ctx = ExecutionContext(
    user_id="user_123",
    request_id="req_456",
    policy=ExecutionPolicy(timeout_seconds=1.0),
)

cael = CAEL(config=CAELConfig())
trace = cael.execute(psi=psi, task=add, ctx=ctx, a=1, b=2)

print(trace.output)          # 3
print(trace.success)         # True
print(trace.runtime_ms)      # float

2. Kernel (Low-Level)

Use Kernel directly when you need:

• Full control without policy layer
• Testing and development
• Building custom orchestrators

from kl_kernel_logic import Kernel, PsiDefinition

def add(a: int, b: int) -> int:
    return a + b

psi = PsiDefinition(
    psi_type="math.add",
    domain="math",
    effect="pure",
)

kernel = Kernel()
trace = kernel.execute(psi=psi, task=add, a=1, b=2)

print(trace.output)          # 3
print(trace.success)         # True
print(trace.runtime_ms)      # float

Recommendation: Start with CAEL for production. Use Kernel for testing or when building custom execution layers.

Foundations Examples

The examples_foundations module contains deterministic operations such as:

• Poisson equation solver in 1D
• Sliding-window smoothing
• Simple trajectory integration

They are used in the test suite and serve as reference operations.

See also: docs/foundational-execution-patterns.md for detailed examples and patterns.

Tests

Run all tests:

pytest

The suite covers:

• Psi semantics and constraints
• envelope behaviour
• kernel execution and trace structure
• CAEL policy bridge
• audit report generation
• foundation operations

Theoretical Foundation

KL Kernel Logic is the reference implementation of KL Execution Theory, a minimal and domain-agnostic execution model.

The 5-Element Execution Chain

KL Execution Theory defines execution as a deterministic chain of five derived elements:

Δ → V → t → G(V) → SS

• Δ (Delta) – Atomic state transition (one Kernel.execute() call)
• V (Behaviour) – Ordered sequence of transitions (trace list)
• t (Time) – Logical time derived from position in V (list index)
• G(V) (Governance) – Policy function evaluated over behaviour
• SS (Shadow State) – Derived audit state from governance evaluation

Each element depends on the previous. The chain is minimal: no element can be removed without losing determinism, auditability, or domain neutrality.

Domain-Agnostic Validation

The theory is domain-neutral and has been validated across multiple domains: mathematical computation (Poisson solvers, integration), text processing, AI inference with policy constraints, and data validation. The same structural properties hold regardless of domain: deterministic execution, complete auditability, replayable behaviour, and transparent governance.

Documentation

• docs/kl_execution_theory_v1.md – Complete formal specification
• docs/execution_theory_in_code.md – Theory-to-code mapping

Roadmap

Current Focus (0.3.x)

• Maintaining API stability
• Bug fixes and polish
• Enhanced documentation and examples
• CI/CD automation

Near Future (0.4.0)

• Richer PolicyEngine interface with context and history
• G(V) governance over trace sequences
• Standardized trace export (JSONL, NDJSON)
• Optional constraint validation

Long Term (0.5.0+)

• Enterprise extensions as separate packages
• Async execution support
• Observability integrations
• Production-scale features

See: docs/roadmap.md for complete roadmap, versioning strategy, and non-goals.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

For bug reports and feature requests, please use the GitHub Issues.

License

MIT License. See LICENSE for details.

Copyright (c) 2025 Lukas Pfister

Changelog

See CHANGELOG.md for detailed version history and migration notes.