Metadata-Version: 2.4
Name: kernell-os-sdk
Version: 2.3.0
Summary: First public release of an agentic runtime for M2M coordination. Machines coordinate, verify, and settle value autonomously.
Project-URL: Homepage, https://kernell.site
Project-URL: Repository, https://github.com/Greco-Italico/kernell-os-sdk
Project-URL: Documentation, https://kernell.site/docs/sdk
Author-email: Kernell OS <dev@kernell.site>
License: MIT
Keywords: agents,ai,autonomous,commerce,kernell,llm,m2m,orchestration
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: cryptography<44,>=42.0
Requires-Dist: httpx<1,>=0.27
Requires-Dist: prometheus-client<1,>=0.20
Requires-Dist: psutil<7,>=5.9
Requires-Dist: pydantic<3,>=2.7
Requires-Dist: redis<6,>=5.0
Requires-Dist: structlog<26,>=24.0
Requires-Dist: tenacity<10,>=8.2
Provides-Extra: all
Requires-Dist: anthropic>=0.25; extra == 'all'
Requires-Dist: cryptography>=41.0.0; extra == 'all'
Requires-Dist: docker>=7.0; extra == 'all'
Requires-Dist: fastapi>=0.100.0; extra == 'all'
Requires-Dist: openai>=1.0; extra == 'all'
Requires-Dist: redis>=5.0; extra == 'all'
Requires-Dist: uvicorn>=0.25.0; extra == 'all'
Provides-Extra: cluster
Requires-Dist: httpx>=0.25.0; extra == 'cluster'
Requires-Dist: redis>=5.0; extra == 'cluster'
Provides-Extra: gui
Requires-Dist: cryptography>=41.0.0; extra == 'gui'
Requires-Dist: fastapi>=0.100.0; extra == 'gui'
Requires-Dist: uvicorn>=0.25.0; extra == 'gui'
Provides-Extra: llm
Requires-Dist: anthropic>=0.25; extra == 'llm'
Requires-Dist: openai>=1.0; extra == 'llm'
Provides-Extra: memory
Requires-Dist: redis>=5.0; extra == 'memory'
Provides-Extra: sandbox
Requires-Dist: docker>=7.0; extra == 'sandbox'
Provides-Extra: test
Requires-Dist: coverage>=7.4.0; extra == 'test'
Requires-Dist: fakeredis[lua]>=2.20.0; extra == 'test'
Requires-Dist: freezegun>=1.4.0; extra == 'test'
Requires-Dist: httpx>=0.27.0; extra == 'test'
Requires-Dist: hypothesis>=6.0.0; extra == 'test'
Requires-Dist: prometheus-client>=0.20.0; extra == 'test'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
Requires-Dist: pytest-mock>=3.12.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Requires-Dist: responses>=0.25.0; extra == 'test'
Description-Content-Type: text/markdown

<div align="center">
  <img src="https://raw.githubusercontent.com/Greco-Italico/kernell-os-sdk/main/logo3d.png" alt="Kernell OS Logo" width="180" height="180">

  # Kernell OS SDK
  ### Policy-driven execution infrastructure for agent systems
</div>

Kernell OS SDK is not a simple LLM wrapper.  
It is an execution control plane that optimizes inference cost, quality, and latency while collecting feedback to improve routing decisions over time.

## What This SDK Is

- Policy-driven inference engine
- Multi-tier execution router (local, cheap API, premium API)
- Quality-aware runtime with verification and safe fallback
- Telemetry + labeling + training pipeline for continuous improvement
- Agent runtime foundation (security, sandboxing, economics, marketplace, governance)

## What This SDK Is Not

- Prompt utility library
- Single-model client wrapper
- Static rule router without learning loop

---

## Core Value Proposition

Traditional flow:

`input -> one LLM`

Kernell OS flow:

`input -> policy decision -> multi-layer execution -> verification -> telemetry -> retraining`

### Why this matters

- Optimize costs without blindly degrading quality
- Route dynamically per task/hardware/risk
- Learn from production behavior (data flywheel)
- Keep fallback safety under uncertainty

---

## Architecture Overview

```text
Task Input
  -> Policy Model (Lite/Pro)
  -> (Optional) Task Decomposition
  -> Execution Layers:
       [Semantic Cache] -> [Local] -> [Cheap API] -> [Premium]
  -> Self Verification
  -> Re-route / Fallback (if needed)
  -> Telemetry
  -> Offline Labeling
  -> Dataset / Fine-tuning Pipeline
```

## Routing Strategy

The router is policy-driven, not difficulty-only:

- `route`: `local | cheap | premium | hybrid`
- `confidence`
- `risk`
- `expected_cost_usd`
- `expected_latency_s`
- `needs_decomposition`

When confidence/risk/economic uncertainty is unsafe, it forces `hybrid` fallback path.

---

## Main Components (Real Modules)

### Router and Policy

- `kernell_os_sdk/router/intelligent_router.py`  
  Orchestrates execution across cache/local/cheap/premium, verification, telemetry.
- `kernell_os_sdk/router/policy_lite.py`  
  Local policy model client with safety overrides.
- `kernell_os_sdk/router/classifier_pro.py`  
  Cloud escalation client for higher-precision routing.
- `kernell_os_sdk/router/types.py`  
  Canonical contracts (`PolicyDecision`, tiers, results).
- `kernell_os_sdk/router/entrypoint.py`  
  Shadow/canary/full rollout entrypoint with safe fallback.

### Quality, Cost, and Context

- `kernell_os_sdk/router/verifier.py` (`SelfVerifier`)
- `kernell_os_sdk/router/estimator.py` (`CostEstimator`)
- `kernell_os_sdk/router/summarizer.py` (`RollingSummarizer`)
- `kernell_os_sdk/router/decomposer.py` (`TaskDecomposer`)
- `kernell_os_sdk/router/model_registry.py` (`ModelRegistry`)

### Telemetry and Learning Loop

- `kernell_os_sdk/router/telemetry_collector.py`  
  Collects anonymized route/outcome/quality signals.
- `kernell_os_sdk/router/offline_labeler.py`  
  Produces optimal-route labels from real outcomes (cost + quality aware).

### Data Pipeline Scripts

- `scripts/policy_build_dataset.py` -> telemetry to labeled dataset
- `scripts/policy_make_sft_jsonl.py` -> labeled dataset to SFT JSONL
- `scripts/policy_train_lora.py` -> LoRA training scaffold
- `scripts/policy_audit_dataset.py` -> distribution and sampling audit

### Runtime, Security, and Infra Domains

- `kernell_os_sdk/runtime/`  
  Firecracker/Docker/Subprocess/hybrid runtime primitives
- `kernell_os_sdk/security/`  
  policy, verifier, SSRF and capability controls
- `kernell_os_sdk/cognitive/`  
  memory graph, execution graph, semantic modules
- `kernell_os_sdk/marketplace/`, `governance/`, `cluster/`, `delegation/`, `escrow/`  
  economic coordination and distributed agent primitives

---

## Data Flywheel

Kernell OS improves routing through a closed learning loop:

1. Runtime emits telemetry from real executions
2. Offline labeler computes optimal route targets
3. Dataset is generated and audited
4. Model fine-tuning is prepared/executed
5. Updated policy models are deployed

This converts routing mistakes into training signal (`underestimation`, `overestimation`, `misroute`) and enables continuous optimization.

---

## Safety and Production Hardening

- Verification-aware routing to reduce low-quality escalations
- Risk-aware and budget-aware fallback to `hybrid`
- Optional Prometheus dependency (non-blocking no-op fallback in runtime metrics)
- Shadow/canary rollout strategy before full traffic cutover
- Rate limiting, sandbox controls, and capability policy modules available in SDK

---

## Installation

```bash
pip install kernell-os
```

Optional observability dependency:

```bash
pip install prometheus_client
```

---

## Minimal Example

```python
from kernell_os_sdk.router import PolicyLiteClient, PolicyLiteConfig

# Integrate PolicyLiteClient into your IntelligentRouter wiring
# based on your local model backend and runtime configuration.
```

See `kernell_os_sdk/router/` modules and tests for concrete integration patterns.

---

## Testing

Router and flywheel suites:

```bash
python -m pytest tests/test_router.py tests/test_data_flywheel.py tests/test_policy_lite.py -q
```

### Containerized "real client" validation

Use this when you want to verify the same path as an external developer:
installing the SDK with `pip` in a clean environment, not from local source.

```bash
cd kernell-os-sdk
docker compose -f deploy/docker-compose.sdk-client.yml up --build --abort-on-container-exit
```

What this stack validates:

- Clean installation from package index (`SDK_PIP_SPEC`, default `kernell-os-sdk`)
- SDK import sanity from installed distribution
- CLI availability (`kernell --help`)
- Minimal router execution path (`IntelligentRouter.execute(...)`) with deterministic mock backend
- Telemetry capture signal (`TelemetryCollector`) to protect the data-flywheel contract
- Policy signal presence in telemetry (`policy_route_predicted`) to catch policy integration regressions
- Graceful failure-mode path (no local models configured) without process crash
- Baseline service dependencies (`redis` + `qdrant`) reachable in compose network
- Structured CI-friendly report (JSON line with `install/import/cli/router/telemetry/policy/failure_mode`)

Useful overrides:

```bash
# Test a pinned prerelease/build
SDK_PIP_SPEC='kernell-os-sdk==2.2.0b1' \
docker compose -f deploy/docker-compose.sdk-client.yml up --build --abort-on-container-exit

# If distribution name differs on your package index:
SDK_DISTRIBUTION_NAME='kernell-os-sdk' \
docker compose -f deploy/docker-compose.sdk-client.yml up --build --abort-on-container-exit

# Disable failure-mode probe when needed:
SDK_SMOKE_FAILURE_MODE=0 \
docker compose -f deploy/docker-compose.sdk-client.yml up --build --abort-on-container-exit

# Optional: check expected telemetry artifact path too
KERNELL_TELEMETRY_PATH=/tmp/kernell_telemetry/telemetry_buffer_latest.jsonl \
docker compose -f deploy/docker-compose.sdk-client.yml up --build --abort-on-container-exit
```

Cleanup:

```bash
docker compose -f deploy/docker-compose.sdk-client.yml down -v
```

### Chaos profile (optional, antifragility checks)

Run the dedicated chaos profile without blocking regular PR validation:

```bash
docker compose -f deploy/docker-compose.sdk-client.yml --profile chaos up --build --abort-on-container-exit sdk-client-chaos
```

Chaos profile expectations:

- `install/import/cli/telemetry/policy/failure_mode` stay `ok`
- `degraded` is `true` (degradation is detected and reported, not hidden)
- controlled degradation is acceptable; process crash is not

---

## Current Status

### Implemented now

- Policy-driven router integration
- Telemetry v2 with policy signals
- Offline labeling pipeline with quality-aware guards
- Dataset audit tooling and sampling workflow
- Regression-tested router/flywheel suites

### Planned / in progress

- Persistent semantic cache backend integration (distributed)
- Full training automation and model promotion gates
- Expanded online feedback correction and deploy gating benchmarks

---

## Open-Core Positioning

- SDK core: open source runtime and routing foundations
- Advanced policy intelligence and cloud services: source-available/commercial layers

---

<div align="center">
  <i>From static LLM calls to adaptive inference infrastructure.</i>
</div>
