Metadata-Version: 2.4
Name: kernell-os-sdk
Version: 2.6.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: fastapi>=0.100.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
Requires-Dist: uvicorn>=0.25.0
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

# 🚀 Kernell OS SDK

## 🧠 What is Kernell OS?

**Kernell OS SDK is an installable agentic runtime that executes, routes, and optimizes AI workloads automatically across multiple models and cost tiers.**

It is not just a library to call LLMs.

It is a system that:

* Decides **how** tasks should be executed
* Optimizes **cost, latency, and quality** in real time
* Learns from production via telemetry
* Improves itself through a continuous data flywheel

---

## 💡 In One Line

> Kernell turns AI inference into an optimized, self-improving system.

---

# 🧱 System Architecture (Layered View)

```
┌──────────────────────────────────────┐
│           Application Layer          │
│   (Agents, copilots, workflows)      │
└──────────────────────────────────────┘
                  ↓
┌──────────────────────────────────────┐
│        Policy & Decision Layer       │
│   (PolicyLite, risk, cost, routing)  │
└──────────────────────────────────────┘
                  ↓
┌──────────────────────────────────────┐
│        Execution & Routing Layer     │
│   (Router, fallback, decomposition)  │
└──────────────────────────────────────┘
                  ↓
┌──────────────────────────────────────┐
│        Model & Cache Layer           │
│ (Local / Cheap / Premium + Cache)    │
└──────────────────────────────────────┘
                  ↓
┌──────────────────────────────────────┐
│        Telemetry & Learning Layer    │
│ (Telemetry, labeling, datasets, FT)  │
└──────────────────────────────────────┘
```

---

# 🔥 Core Capabilities

## 🧠 Intelligent Routing (Policy Engine)

Automatically selects the best execution strategy:

* `local` → fastest, cheapest
* `cheap` → low-cost cloud models
* `premium` → high-quality models
* `hybrid` → safe fallback path

Decisions are based on:

* confidence
* risk
* expected cost
* latency constraints

---

## 🤖 Execution Engine

* Task decomposition
* Multi-model orchestration
* Automatic fallback
* Parallel execution support

---

## 💰 Cost-Aware Optimization

* Expected vs real cost tracking
* Budget enforcement
* Savings measurement (`savings_pct`)

---

## 📊 Telemetry & Data Flywheel

Every execution generates structured telemetry:

* routing decisions
* cost and latency
* success/failure
* policy signals

Used to:

* debug production issues
* build training datasets
* improve policy models

---

## 🔁 Continuous Learning Pipeline

Built-in tools:

* dataset generation
* labeling from real outcomes
* SFT dataset creation
* LoRA fine-tuning pipeline

---

## ⚡ Semantic Cache (L1 + L2)

* In-memory cache (L1)
* Vector database (Qdrant) (L2)

Reduces:

* latency
* cost
* repeated computation

---

## 🌐 Classifier-Pro API

* FastAPI server
* External policy decisions
* Rate limiting

---

## 🧪 Production-Grade Validation

* Containerized install validation
* Smoke tests (real execution)
* Chaos testing (failure scenarios)
* CI release gates
* Benchmark system

---

# ⚡ Quickstart

## 1. Install

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

---

## 2. Basic Usage

```python
from kernell_os_sdk.router import IntelligentRouter

router = IntelligentRouter()
results = router.execute("Explain quantum computing simply")

for r in results:
    print(r.output)
```

---

# 💥 Real Example (Value Demonstration)

### Task:

> "Summarize a 10-page document and extract key insights"

### Without Kernell:

* Uses premium model directly
* Cost: **$0.25**
* Latency: **3.2s**

### With Kernell:

* Classifies as medium complexity
* Uses cheap + partial routing
* Cost: **$0.03**
* Latency: **1.9s**

### Result:

* 💰 **~88% cost reduction**
* ⚡ **~40% faster**
* ✅ Same quality (verified)

---

# 🧠 How It Works (Internal Flow)

```
Input
  ↓
PolicyLite → decides route (local/cheap/premium/hybrid)
  ↓
Router → executes plan
  ↓
Fallbacks (if needed)
  ↓
Result aggregation
  ↓
Telemetry capture
  ↓
Dataset + training loop
```

---

# 🧪 Validation Modes

## 🟢 Normal Mode (Release Gate)

Validates:

* install
* import
* CLI
* router execution
* telemetry
* policy
* failure-mode

---

## 🟡 Chaos Mode (Resilience)

```bash
docker compose --profile chaos up
```

Validates:

* degraded execution
* service failures
* fallback behavior
* system resilience

---

# 📊 Benchmarking

Run benchmark:

```bash
python scripts/benchmark_runner.py
```

Generate report:

```bash
python scripts/benchmark_report.py
```

Metrics:

* savings_pct
* latency_delta
* quality_guardrail

---

# 🔁 Data Flywheel

```
Production → Telemetry → Labeling → Dataset → Training → Better Policy
```

---

# 🧩 Use Cases

* AI copilots
* autonomous agents
* cost-optimized inference systems
* multi-model orchestration

---

# 🚀 Roadmap

* Fine-tuned policy model (LoRA)
* Auto-install model on init
* Production deployment tooling
* Advanced chaos testing (latency, partial failures)

---

# 🧾 License

MIT

---

# ⚡ Final Note

Kernell is not just an SDK.

It is a system for managing intelligence as a resource.
