Metadata-Version: 2.4
Name: mcpaisuite-kernelmcp
Version: 1.0.3
Summary: The sovereign orchestrator — connects all MCP AI suite libraries into an autonomous agent
Project-URL: Homepage, https://github.com/gashel01/kernelmcp
Project-URL: Repository, https://github.com/gashel01/kernelmcp
Author-email: gashel01 <gaeldev@gmail.com>
License: AGPL-3.0-or-later
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: 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: 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: 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.dev).

## 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
- **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
- **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
```

## 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")
```

## 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

AGPL-3.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 [gaeldev@gmail.com](mailto:gaeldev@gmail.com).
