Metadata-Version: 2.4
Name: mcpaisuite-kernelmcp
Version: 1.1.0
Summary: The sovereign orchestrator — connects all MCP AI suite libraries into an autonomous agent
Project-URL: Homepage, https://mcpaisuite.com/libraries/kernelmcp
Project-URL: Repository, https://github.com/gashel01/kernelmcp
Author-email: gashel01 <contact@mcpaisuite.com>
License: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: litellm>=1.0
Requires-Dist: mcp>=1.0
Requires-Dist: mcpaisuite-evalmcp>=1.0
Requires-Dist: mcpaisuite-ltpmcp>=1.0
Requires-Dist: mcpaisuite-websearchmcp>=1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: structlog>=24.0
Provides-Extra: all
Requires-Dist: fastapi>=0.100; extra == 'all'
Requires-Dist: fastapi>=0.111; extra == 'all'
Requires-Dist: httpx>=0.25; extra == 'all'
Requires-Dist: mcpaisuite-memorymcp>=1.0; extra == 'all'
Requires-Dist: mcpaisuite-planningmcp>=1.0; extra == 'all'
Requires-Dist: mcpaisuite-ragmcp>=1.0; extra == 'all'
Requires-Dist: mcpaisuite-sandboxmcp>=1.0; extra == 'all'
Requires-Dist: mcpaisuite-schedulermcp>=1.0; extra == 'all'
Requires-Dist: mcpaisuite-workspacemcp>=1.0; extra == 'all'
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20; extra == 'all'
Requires-Dist: opentelemetry-sdk>=1.20; extra == 'all'
Requires-Dist: prometheus-client>=0.17; extra == 'all'
Requires-Dist: uvicorn>=0.23; extra == 'all'
Requires-Dist: uvicorn>=0.29; extra == 'all'
Provides-Extra: api
Requires-Dist: fastapi>=0.100; extra == 'api'
Requires-Dist: uvicorn>=0.23; extra == 'api'
Provides-Extra: dev
Requires-Dist: httpx>=0.25; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.1; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: memorymcp
Requires-Dist: mcpaisuite-memorymcp>=1.0; extra == 'memorymcp'
Provides-Extra: metrics
Requires-Dist: prometheus-client>=0.17; extra == 'metrics'
Provides-Extra: planningmcp
Requires-Dist: mcpaisuite-planningmcp>=1.0; extra == 'planningmcp'
Provides-Extra: ragmcp
Requires-Dist: mcpaisuite-ragmcp>=1.0; extra == 'ragmcp'
Provides-Extra: sandboxmcp
Requires-Dist: mcpaisuite-sandboxmcp>=1.0; extra == 'sandboxmcp'
Provides-Extra: schedulermcp
Requires-Dist: mcpaisuite-schedulermcp>=1.0; extra == 'schedulermcp'
Provides-Extra: tracing
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20; extra == 'tracing'
Requires-Dist: opentelemetry-sdk>=1.20; extra == 'tracing'
Provides-Extra: webhooks
Requires-Dist: fastapi>=0.111; extra == 'webhooks'
Requires-Dist: httpx>=0.25; extra == 'webhooks'
Requires-Dist: uvicorn>=0.29; extra == 'webhooks'
Provides-Extra: workspacemcp
Requires-Dist: mcpaisuite-workspacemcp>=1.0; extra == 'workspacemcp'
Description-Content-Type: text/markdown

# kernelmcp

> The sovereign orchestrator -- connects all MCP AI suite libraries into an autonomous agent

Part of the [MCP AI Suite](https://mcpaisuite.com).

## Features

- **ReAct engine** with autonomous Thought-Action-Observation loop driven by LLM
- **LTP (Lean Task Protocol)** compiler turns goals into deterministic execution plans in one LLM call
- **Dry-run / simulation** -- `kernel.run(goal, dry_run=True)` plans without executing any tool (no side effects); records the tool calls it *would* make. Also `kernelmcp run --dry-run`. The LLM still runs, so tokens are still spent.
- **A/B testing of constitutions** -- `run_ab(...)` runs a goal under two constitutions and reports success/cost/token deltas + a winner (CLI `kernelmcp ab`, MCP tool `ab_test`, API `POST /ab`)
- **Deterministic graph nodes** -- a graph node can run a governed tool or sandboxed Python (`tool`/`code` node), not just an LLM agent. Runs through the tool chokepoint (budget/audit/DLP), no LLM; `${input}` consumes the upstream node's output. Same engine and visual editor as agent graphs
- **Dynamic map-reduce (`map` node)** -- fan out a `body` (tool / code / agent) over a **runtime-determined** list and reduce the results -- the parallel width is decided at execution time, not drawn in the graph. `over` resolves a parent's output / a `${channel:NAME}` to a list; each branch sees `${item}`/`${index}`; results are merged by a named reducer (`append`/`concat`/`sum`/`dedup`/`last`/`merge`) into the node output and an optional named `into` channel. Each branch is a governed, spanned step (its tool calls hit the same chokepoint). **Governance note:** the graph path has no static plan verifier (unlike compiled LTP plans), so dynamic fan-out is bounded at **runtime** -- a per-node `max_fanout` (hard-ceilinged) plus per-call budget/quota -- rather than statically proven. Use the LTP path when you need a statically verifiable plan
- **Programmatic graph API** -- build cyclic, stateful agent graphs in pure Python (`from kernelmcp.graph import Graph, END`): `add_node(name, fn)` runs an arbitrary Python callable that shares a state dict, `add_edge(a, b)` (a self-edge is a **bounded loop** with an early-exit `{"__stop__": True}` signal), `add_conditional_edge(src, router, mapping)` for branching, plus **checkpoint/resume** (`GraphCheckpointer`) that snapshots execution per wave. It's a thin facade over the same executor as the visual builder, so parallel waves, governed `tool`/`code` nodes, per-node spans and map-reduce all work unchanged. **Note:** callable nodes are your own in-process code (like a LangGraph node) -- not sandboxed and not through the tool chokepoint (governance still applies to any kernel *tools* they call); use a `code` node for sandboxed execution. Graphs with Python callables are library-only by nature (a function can't cross JSON/MCP/HTTP)
- **Suite orchestration** -- wires websearchmcp, sandboxmcp, workspacemcp, planningmcp, schedulermcp, memorymcp, and ragmcp in-process
- **Smart routing** -- TaskSupervisor selects cloud, local, or fast model per task complexity
- **Sub-agent system** -- spawn specialized agents (code, research, file, memory) for subtasks
- **Budget enforcement** with per-task and per-namespace token/cost caps
- **DLP secret guard** -- redacts secrets (AWS keys, tokens, private keys, connection strings) in tool results *before they reach the model*, and blocks outbound tool calls whose arguments carry a secret. Enforced at the tool chokepoint -- deterministic, not asked of the model. Opt-in via `enable_dlp`; emits `secret.redacted` / `secret.blocked` events
- **Agent-JIT cache (experimental, situational)** -- amortizes repeated task *families*: the first instance reasons normally and its `execute_code` solution is cached by a semantic signature; a later instance is validated once by shadow execution (cached pattern vs cold engine, outputs compared deterministically) and then reused. When it engages, a reuse measured **~34× cheaper** (~330 vs ~11k tokens) and never ships an unvalidated answer (falls back to the full engine on mismatch). **Honest caveat:** the gain is **only net-positive on repetitive workloads that reliably route through `execute_code`** — engagement hinges on that, which is non-deterministic for simple tasks, so on low-repetition or non-code-routed traffic it can be **net-neutral to ~+15%** (an un-amortized shadow pass). Hence **off by default**. Opt-in via `jit=True` / `KERNELMCP_JIT`; inspect with `kernel.jit_stats()`
- **Circuit breaker and fallback chain** for resilient LLM calls with automatic retry and backoff
- **Full audit trail** via SQLite -- every tool call, cost, and token count logged
- **Prometheus metrics** -- a `/metrics` endpoint on the kernel API (and the Hub) exposes tool-call counts + success rate + duration, tasks by status, tokens and cost. Instrumented at the single governed tool chokepoint, so every execution path is covered. Opt-in via the `[metrics]` extra (`pip install mcpaisuite-kernelmcp[metrics]`); a graceful no-op (empty exposition) when `prometheus-client` isn't installed
- **OpenTelemetry export** -- `KernelFactory.create(otel_endpoint="http://localhost:4317")` exports each finished task's live span tree (parent/child, tokens/cost/model attributes) to any OTLP backend (Jaeger, Zipkin, Grafana Tempo). Opt-in via the `[tracing]` extra; a graceful no-op when the OTel SDK isn't installed or no endpoint is set
- **Event bus** for real-time streaming and progress callbacks
- **Elicitation** -- agent can pause execution to ask user questions
- **Self-hosted Hub connector** -- `connect_hub()` reports an embedded kernel's traces to your own Hub for monitoring, with opt-in remote control (ping/stats/set_config/run/cancel) over an outbound-only connection

## Installation

```bash
pip install mcpaisuite-kernelmcp
# Optional extras:
pip install mcpaisuite-kernelmcp[dev]          # Development tools
pip install mcpaisuite-kernelmcp[all]          # All suite libraries + webhooks + REST API
pip install mcpaisuite-kernelmcp[memorymcp]    # Memory integration
pip install mcpaisuite-kernelmcp[sandboxmcp]   # Sandbox integration
pip install mcpaisuite-kernelmcp[planningmcp]  # Planning integration
```

## Setup (interactive)

```bash
kernelmcp init   # pick model, API key, and libraries -> writes kernelmcp.config.yaml
kernelmcp start --config kernelmcp.config.yaml
```

## Quick Start

```python
from kernelmcp import KernelFactory

kernel = KernelFactory.from_env()
task = await kernel.run("Research the latest Python 3.13 features and summarize them")
print(task.summary)
print(f"Cost: ${task.total_cost:.4f}, Tokens: {task.total_tokens}")
```

## MCP Server

```bash
# Agent mode (kernel LLM drives the ReAct/LTP loop):
kernelmcp start --transport stdio --mode agent

# Router mode (client LLM drives tool selection, kernel routes):
kernelmcp start --transport stdio --mode router

# SSE transport:
kernelmcp start --transport sse --port 8080
```

## Configuration

| Variable | Default | Description |
|---|---|---|
| `KERNELMCP_MODEL` | `claude-sonnet-4-6` | Primary LLM model |
| `KERNELMCP_FAST_MODEL` | `claude-haiku-4-5-20251001` | Fast model for simple tasks |
| `KERNELMCP_LOCAL_MODEL` | `ollama/mistral` | Local model fallback |
| `KERNELMCP_ROUTING` | `true` | Enable smart model routing |
| `KERNELMCP_MAX_TURNS` | `20` | Max ReAct turns per task |
| `KERNELMCP_MAX_TOKENS` | `50000` | Token budget per task |
| `KERNELMCP_DLP` | `false` | Redact secrets in tool I/O + block secret exfiltration (DLP) |
| `KERNELMCP_JIT` | `false` | Reuse shadow-validated solution patterns across repeated task families (Agent-JIT) |
| `KERNELMCP_NANO` | `false` | Fast path for trivial single-shot tasks (skips constitution/full tools) |
| `KERNELMCP_NAMESPACE` | `default` | Default tenant namespace |
| `ANTHROPIC_API_KEY` | -- | API key for Claude models |

Or configure via YAML:

```yaml
llm_model: claude-sonnet-4-6
enable_routing: true
max_turns: 20
memory:
  episodic_store: sqlite
workspace:
  root_path: /data/workspace
sandbox:
  enable_host_access: true
```

```python
kernel = KernelFactory.from_yaml("config.yaml")
```

## Kubernetes (Helm)

A Helm chart under [`helm/kernelmcp`](helm/kernelmcp) deploys the HTTP API server
(`kernelmcp-api`, exposing `/health` and Prometheus `/metrics`) with probes, a config
ConfigMap, an optional API-key Secret, optional bundled Redis, Ingress, and HPA.

```bash
# Build the image (no image is published yet) and load/push it where your cluster can pull it:
docker build -t kernelmcp:1.0.5 .
# kind load docker-image kernelmcp:1.0.5      # for a local kind cluster

# Install (set your provider key; a Secret is created for it):
helm install kernel ./helm/kernelmcp \
  --namespace kernelmcp --create-namespace \
  --set llm.model=claude-sonnet-4-6 \
  --set llm.apiKey=$ANTHROPIC_API_KEY

# Optional: bundled Redis, Ingress, autoscaling
helm upgrade kernel ./helm/kernelmcp --reuse-values \
  --set redis.enabled=true --set ingress.enabled=true --set autoscaling.enabled=true

# Verify
kubectl -n kernelmcp port-forward svc/kernel-kernelmcp 8000:8000
curl localhost:8000/health
```

Use an existing Secret instead of an inline key with
`--set llm.existingSecret=my-secret --set llm.existingSecretKey=api-key`. See
[`helm/kernelmcp/values.yaml`](helm/kernelmcp/values.yaml) for all options. (Raw k8s
manifests also live in [`k8s/`](k8s) if you prefer `kubectl apply`.)

## Self-Hosted Hub (Monitoring & Control)

Embed kernelmcp in your own app and point it at a self-hosted Hub to monitor your
kernels from one place -- and optionally control them. Monitoring is telemetry push
over an **outbound-only** connection (no inbound port on your app); control is
**opt-in**.

```python
from kernelmcp import KernelFactory, connect_hub

kernel = KernelFactory.from_env()

# Monitoring only (always on once connected):
await connect_hub(kernel, hub_url="http://my-hub:8007", project="prod", api_key="kmh_...")

# ...or also let the Hub send commands to this kernel (opt-in):
await connect_hub(kernel, hub_url="http://my-hub:8007", project="prod",
                  api_key="kmh_...", allow_control=True)

# Use the kernel normally -- finished tasks show up in your Hub.
```

`connect_hub(...)` is fail-safe and a no-op if unconfigured (it also reads
`KERNELMCP_HUB_URL` / `KERNELMCP_HUB_KEY` / `KERNELMCP_HUB_PROJECT` from the
environment), so it is always safe to call unconditionally. With `allow_control=True`
the Hub can send `ping` / `stats` / `set_config` / `run` / `cancel` commands; pass
`run_handler(goal)` to customize how `run` executes. Returns a `HubConnector` (or
`None` if unconfigured); call `await connector.stop()` to disconnect.

## API Reference

### KernelPipeline

The main orchestrator managing tasks, budgets, and all suite libraries.

```python
await kernel.run(goal, namespace="default", mode="", budget_usd=None, constitution=None)
await kernel.call_tool(tool_name, arguments, namespace="default")
await kernel.spawn_agent(agent_type, task, namespace="default", max_turns=None)
await kernel.get_stats()
await kernel.health()
```

### KernelFactory

```python
KernelFactory.default()             # Minimal kernel, no integrations
KernelFactory.from_env()            # Build from environment variables
KernelFactory.from_yaml("cfg.yaml") # Build from YAML config
KernelFactory.full_suite()           # All libraries wired in-process
KernelFactory.create(llm_model=..., memory_pipeline=..., ...)  # Full control
```

## Architecture

KernelPipeline wraps a ReActEngine that drives the Thought-Action-Observation loop. A SuiteOrchestrator holds references to all sub-library pipelines (memory, workspace, sandbox, planning, scheduler, RAG) and exposes their tools to the engine. TaskSupervisor routes each task to the appropriate LLM model (cloud, fast, or local) based on complexity, while BudgetEnforcer and CircuitBreaker provide cost control and resilience.

## Testing

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

## License

Apache-2.0 — see [LICENSE](LICENSE).

Open source for individuals and open-source projects. For commercial use in closed-source products, a commercial license is available — contact [contact@mcpaisuite.com](mailto:contact@mcpaisuite.com).
