Metadata-Version: 2.4
Name: kernell-core
Version: 1.0.2
Summary: The secure runtime and control plane for autonomous economic agents.
License: Proprietary
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn>=0.23.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: qdrant-client>=1.7.0
Requires-Dist: redis>=5.0.0

# Kernell

Run AI agents with automatic cost optimization.

Agent runtime with deterministic economic control (estimate, hold, settle, refund).

Kernell executes agents, estimates cost before running, charges only what is actually used, and refunds the rest automatically.
No overpay. No guesswork. Full control.

## Quick Demo (60 seconds)

```bash
pip install kernell-os-sdk
export KERNELL_API_KEY=your_key

kernell run --task-type financial
```

Example output:

```text
[Estimate]  0.026000 KERN
[Actual]    0.024000 KERN
[Refund]    0.002000 KERN
[Remaining] 9.976000 KERN
Saved vs estimate: 0.002000 KERN
✔ Economic loop settled
```

## What Just Happened?

Kernell runs every task through a deterministic economic loop:

```text
estimate -> hold -> execute -> capture -> refund -> ledger
```

- Estimates cost before execution
- Reserves budget (no uncontrolled spend)
- Executes the agent
- Charges only actual usage
- Refunds the difference automatically

Every execution is economically optimized by design.

## Why Kernell?

Most agent frameworks focus on execution. Kernell adds what is missing:

- Cost control: prevent uncontrolled token usage
- Deterministic billing: estimate vs actual, always visible
- Automatic refunds: you never overpay
- Execution abstraction: run tasks without micromanaging models

## Usage

Run tasks:

```bash
kernell run --task-type simple
kernell run --task-type financial
kernell run --task-type multi_agent
```

Optional flags:

- `--api-key <your_key>`
- `--base-url <http://localhost:8000>`
- `--legacy`

Environment:

```bash
export KERNELL_API_KEY=your_key
export KERNELL_BASE_URL=http://localhost:8000
```

## Architecture (Simplified)

```text
CLI -> API -> ExecutionManager -> SpendGuard -> Ledger
```

- `ExecutionManager`: orchestrates execution
- `SpendGuard`: enforces budget and settlement
- `Ledger`: records every transaction

## Legacy Mode

```bash
kernell run --legacy
```

Uses the previous execution path without full economic guarantees.

## Dashboard (Coming Soon)

A visual interface for inspecting executions, costs, and routing decisions is under development.

The current primary interface is the CLI (`kernell run`).

## Experimental: DevLayer

DevLayer is an experimental internal system for building and debugging agents inside Kernell.

It is not yet part of the public workflow.

## Future: Marketplace

Kernell may support an agent marketplace where tasks can be executed and settled programmatically.

That would include task publication, agent execution, result validation, and automated payment.

This is not part of the current production flow.

## Status

- CLI functional
- Economic execution loop (v2)
- Advanced features are not yet part of the default flow

## Roadmap (High Level)

- Persistent ledger
- Improved routing strategies
- Scalable remote execution
- Extended economic layer

## Positioning

Kernell is not just an agent runner.
It is the execution layer for economically efficient AI agents.

## Contributing

Early stage. Feedback is highly valuable.

## License

TBD
