Kytchen

Too many cooks in the kitchen. Yes chef.

BYOLLM MCP servers for recursive reasoning over documents. Kytchen is your organized prep space: pantry (storage) + prep (tools) + sauce (audit trail), so your LLM can cook the final answer.

Quick Start

pip install 'kytchen[mcp]'
kytchen-rlm install        # auto-detects Claude Desktop, Cursor, Windsurf, VS Code
kytchen-rlm doctor         # verify installation

What This Repo Contains

Kytchen is a monorepo that includes:

• kytchen/: the core Python package
  • RLM core (recursive reasoning loop)
  • Sandboxed REPL and built-in analysis helpers
  • MCP servers (kytchen-mcp, kytchen-local, kytchen-mcp-cloud)
  • Cloud API (FastAPI) for hosted datasets + runs + streaming
  • Exporters ("sauce" / audit trail → Markdown/PDF, etc.)
• kytchen-sdk/: a separate Python SDK package (kytchen_sdk) for the Cloud API
• kytchen-web/: the Next.js dashboard + TypeScript client (UI for datasets/runs/streaming)
• docs/: product + architecture docs

If you’re handing this to another AI for advice, the key is: Kytchen is BYOLLM. It provides context infrastructure + tools + audit trail; it does not provide model inference.

High-Level Architecture

There are three related but distinct ways to use Kytchen:

1. Local MCP server (kytchen-local)

   • No DB required
   • Stores context in a sandboxed Python REPL session and exposes tools via MCP

2. Cloud API (kytchen.api.app)

   • FastAPI backend for datasets/runs/tool sessions
   • Supports streaming query progress (SSE)
   • Intended to back the web dashboard + SDKs

3. SDKs / Web UI

   • kytchen-sdk/ (Python) and kytchen-web/ (Next.js + TS client)
   • Call the Cloud API

Conceptually:

┌──────────────────────────────────────────────────────────┐
│ Your LLM client (Claude/Cursor/Windsurf/...)             │
│ - Has the model subscription / provider key (BYOLLM)     │
└──────────────────────────────────────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────────────┐
│ Kytchen (tools + context + evidence)                     │
│ - Pantry: datasets/context stored once                   │
│ - Prep: tools to search/peek/compute                     │
│ - Sauce: citations/evidence + metrics + trajectory       │
└──────────────────────────────────────────────────────────┘

Repository Layout

.
├── kytchen/                      # core python package
│   ├── core.py                   # recursive loop (RLM runner)
│   ├── repl/                      # sandboxed REPL + helpers + citations
│   ├── mcp/                       # MCP servers (cloud + local)
│   ├── api/                       # FastAPI backend (Cloud)
│   ├── exporters/                 # sauce/audit exports
│   └── converters/                # pdf/docx/xlsx → text
├── kytchen-sdk/                  # Python SDK (httpx client)
├── kytchen-web/                  # Next.js dashboard + TS client
└── docs/                         # product + architecture docs

File Converters (PDF / DOCX / XLSX)

Install optional converter dependencies:

pip install 'kytchen[mcp,converters]'

Then use these MCP tools (in kytchen-local) to load large documents without context stuffing:

convert_pdf(file_path="...", pages="1-5", context_id="doc")
convert_docx(file_path="...", context_id="doc")
convert_xlsx(file_path="...", formulas="evaluated", context_id="sheet")

Optional OCR:

pip install 'kytchen[ocr]'

{
  "mcpServers": {
    "kytchen": {
      "command": "kytchen",
      "env": { "KYTCHEN_API_KEY": "kyt_sk_..." }
    },
    "kytchen-local": {
      "command": "kytchen-local"
    }
  }
}

How It Works

┌──────────────────────────────────────────────────────────────────┐
│  CONTEXT  →  stored once as `ctx`                                │
└──────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌──────────────────────────────────────────────────────────────────┐
│  🔧 80+ TOOLS                                                    │
├──────────────────────────────────────────────────────────────────┤
│  extract_*  │ emails, IPs, money, dates, URLs, functions, TODOs │
│  grep/head  │ filter lines, sort, uniq, columns                 │
│  search     │ regex with context, contains, find_all            │
│  stats      │ word_count, frequency, ngrams, diff               │
│  transform  │ replace, split, before/after, normalize           │
│  validate   │ is_email, is_url, is_json, is_ip                  │
│  convert    │ to_json, to_snake_case, slugify                   │
└──────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌──────────────────────────────────────────────────────────────────┐
│  📋 EVIDENCE  →  cite() accumulates provenance with line numbers │
└──────────────────────────────────────────────────────────────────┘
                                 │
                        ┌────────┴────────┐
                        ▼                 ▼
                    Continue          Finalize
                  (loop back)    (answer + citations)

The model sees metadata, not full text. It writes Python to explore iteratively. Sauce (evidence) auto-accumulates.

Kytchen Cloud API (FastAPI)

The Cloud API lives in kytchen/api/app.py.

Core endpoints (high signal):

• GET /healthz: health check
• GET /v1/datasets: list datasets for workspace (workspace comes from API key)
• POST /v1/datasets: upload dataset (multipart/form-data)
• POST /v1/query: run a query and return a full QueryResult
• POST /v1/query/stream: SSE streaming query progress ("Glass Kitchen")
• POST /v1/tool_call: tool execution endpoint (powers the sandbox + citations)

BYOLLM detail: /v1/query and /v1/query/stream accept a provider and provider_api_key so the user can bring their own Anthropic/OpenAI key. Kytchen is not an inference service.

QueryResult shape

The backend returns:

• id: run id
• answer: string
• evidence: list of citations (snippet + optional line_range + note)
• metrics: token/cost accounting (baseline estimate + actual)

Streaming (/v1/query/stream)

This endpoint is text/event-stream and emits JSON payloads in the form:

• {"type": "started", ...}
• {"type": "step", ...} (trajectory updates)
• {"type": "completed", ...} or {"type": "error", ...}

If you’re integrating a UI, the step events are what power real-time progress rendering.

Python SDK (Cloud)

The Python SDK lives in kytchen-sdk/ and is intended for calling the Cloud API from Python apps.

• Entry point: kytchen_sdk.client.KytchenClient
• Dataset operations: client.datasets.*
• Query:
  • await client.query(...) → QueryResult
  • async for event in client.query_stream(...) → RunEvent stream (SSE)

See kytchen-sdk/README.md and kytchen-sdk/examples/basic.py.

Web Dashboard

The Next.js app is in kytchen-web/.

It is meant to:

• manage workspaces/datasets
• visualize query progress via streaming ("open kitchen")
• show metrics + evidence ("sauce")

See kytchen-web/README.md for frontend-local setup.

Example

You: Load this contract and find all liability exclusions

[AI calls load_context, search_context, cite(), evaluate_progress, finalize]

AI: Found 3 liability exclusions:
    1. Section 4.2: Consequential damages excluded (lines 142-158)
    2. Section 7.1: Force majeure carve-out (lines 289-301)
    3. Section 9.3: Cap at contract value (lines 445-452)

    Sauce: [4 citations with line ranges]

When to Use

# Examples
emails = extract_emails()  # Auto-extracts from ctx
money = extract_money()    # Finds $1,234.56 patterns
errors = grep("ERROR")     # Filter lines
word_frequency(top_n=10)   # Most common words

kytchen-rlm install              # Interactive installer
kytchen-rlm install <client>     # Install to specific client
kytchen-rlm uninstall <client>   # Remove from client
kytchen-rlm doctor               # Verify installation

Development

git clone https://github.com/shannon-labs/kytchen.git
cd kytchen
pip install -e '.[dev,mcp]'
pytest -q  # 230 tests

Backend API (dev mode)

pip install -e '.[dev,api]'
export KYTCHEN_DEV_MODE=1
uvicorn kytchen.api.app:app --reload

MCP server (local)

pip install -e '.[mcp]'
python -m kytchen.mcp.server

Frontend (Next.js)

cd kytchen-web
npm install
npm run dev

Self-Hosting

The repo includes Docker assets (see docker-compose.yml at the repo root if present in your checkout).

At minimum you’ll need:

• a way to store dataset bytes (filesystem / S3-compatible storage / MinIO)
• an API key bootstrap flow (for local dev, a static key is fine)

If you’re self-hosting and using BYOLLM:

• Your client still supplies provider_api_key when calling /v1/query.

Configuration

Common environment variables:

• KYTCHEN_DEV_MODE=1: run the API in in-memory mode (no DB)
• KYTCHEN_PROVIDER: default provider name (e.g. anthropic, openai)
• KYTCHEN_MODEL: default model name

The web app uses kytchen-web/.env.local for Supabase + API endpoints.

Glossary (Project Terms)

• Pantry: stored datasets/context
• Prep: tools and sandboxed REPL operations
• Sauce: evidence/citations (provenance)
• Ticket / Run: a query execution with a trajectory
• Trajectory: step-by-step trace of the reasoning loop
• Glass Kitchen: streaming progress UX (SSE)

If You’re Another AI Reading This

Useful entry points (high-signal files):

• kytchen/core.py: RLM loop orchestration, trajectory creation, provider calls
• kytchen/repl/sandbox.py + kytchen/repl/helpers.py: sandbox + evidence (cite) primitives
• kytchen/api/app.py: Cloud API routes (/v1/query, /v1/query/stream, datasets)
• kytchen-sdk/kytchen_sdk/client.py: Python SDK calling conventions + expected shapes
• docs/WORKSPACE_ARCHITECTURE.md: product + API design intent

When giving advice, clarify:

• Is the goal MCP local tooling or Cloud API + dashboard?
• Is the issue about streaming, evidence/audit, dataset processing, or self-hosting?

Recent Changes

v0.2.0 (December 2025)

80+ new REPL helpers for document analysis:

• 16 extraction functions (emails, IPs, money, dates, phones, URLs, paths, versions, UUIDs, functions, classes, TODOs, log levels)
• 8 statistics (word/line/char count, word frequency, n-grams)
• 12 grep-like line operations (head, tail, grep, sort, uniq, columns)
• 15 text manipulation (replace, split, before/after, truncate, normalize)
• 6 pattern matching (contains, count_matches, find_all)
• 4 comparison (diff, similarity)
• 11 collection utilities (dedupe, flatten, group_by, frequency)
• 7 validators (is_email, is_url, is_ip, is_uuid, is_json)
• 11 converters (to_json, to_snake_case, slugify)

30+ new builtins: map, filter, iter, next, repr, chr, ord, pow, divmod, hash, id, callable, frozenset, bytes, slice...

6 new allowed imports: random, string, hashlib, base64, urllib.parse, html

v0.1.3 (December 2025)

• Added type builtin to sandbox
• Added NameError and AttributeError exceptions

Research

Inspired by Recursive Language Models by Alex Zhang and Omar Khattab.

License

MIT