curry-leaves 1.0.0__tar.gz

curry_leaves-1.0.0/.gitignore

@@ -0,0 +1,34 @@
+# Python bytecode and caches
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Build and packaging artifacts
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test and coverage artifacts
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Type checker and linter caches
+.mypy_cache/
+.ruff_cache/
+.pyre/
+
+# IDE and OS files
+.vscode/
+.idea/
+.DS_Store
+
+# Local agent-tooling state
+.claude/

curry_leaves-1.0.0/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-07-08
+
+### Added
+
+- Initial release of Curry Leaves for Python — a provider-agnostic, multi-agent
+  kernel for building AI agents: streaming tool-use loop, subagents, skills,
+  thinking, permissions, sessions, and compaction. A faithful port of the
+  [TypeScript kernel](https://github.com/ilayanambi-ponramu/curry-leaves-ts),
+  module-for-module.
+- Core engine (`agent_loop`), stateful driver (`Runner`), and stateless agent
+  definitions (`Agent`), with agent-as-tool delegation (`task`) and one-way
+  handoff (`transfer`).
+- Providers for Anthropic, OpenAI, and Ollama (OpenAI-compatible), with
+  automatic provider inference from model id.
+- Tool system with pydantic schemas, risk-based permission fallback, deferred
+  tool discovery via `search_tools`, and blob-backed result capping.
+- **MCP (Model Context Protocol) client support** — connect stdio or HTTP MCP
+  servers (`McpServerStdio` / `McpServerHttp` / `McpServerManager`), pick
+  specific tools with `mcp_tools()`, or load server definitions from
+  `settings.json`'s `mcpServers` key. Goes beyond the TypeScript sibling, which
+  lists MCP as a non-goal.
+- Permission engine with per-call resolution (deny > per-tool allow > standing
+  approval > per-tool ask > default > risk fallback).
+- Auto-thinking (reasoning-effort classifier) and auto-compaction near context
+  limits.
+- Skills system with progressive disclosure from `~/.curry-leaves/skills/` and
+  `.curry-leaves/skills/`.
+- Model catalog sourced from models.dev (context windows, pricing).
+- Session recording to `<home>/sessions/<id>/`.
+- Two bundled CLIs: a full-screen Textual TUI (`curry-leaves`, alias `curry`)
+  and a line REPL (`curry-leaves-repl`).
+- Example scripts covering basic usage, streaming, custom tools, structured
+  output, subagents, host/permissions, and MCP tools.
+- Test suite for the MCP subsystem (`tests/mcp`); strict `mypy` across `src/`.

curry_leaves-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,166 @@
+# Contributing to curry-leaves
+
+Thanks for your interest in improving **curry-leaves** — bug reports, features, docs, and tests are all
+welcome. This guide covers how to get set up, the conventions that keep the codebase coherent, and
+how to extend the kernel.
+
+By participating, you agree to keep interactions respectful and constructive.
+
+## Table of contents
+
+- [Ways to contribute](#ways-to-contribute)
+- [Development setup](#development-setup)
+- [Project layout](#project-layout)
+- [Pull request workflow](#pull-request-workflow)
+- [Code conventions](#code-conventions)
+- [Extending the kernel](#extending-the-kernel)
+- [Commit messages](#commit-messages)
+- [Reporting bugs](#reporting-bugs)
+- [License](#license)
+
+## Ways to contribute
+
+- **Report a bug** — open an issue with a minimal reproduction (see [Reporting bugs](#reporting-bugs)).
+- **Propose a feature** — open an issue describing the use case *before* writing code, so we can
+  agree on the approach.
+- **Improve docs** — READMEs, code comments, and examples all count.
+- **Add tests** — the MCP subsystem has a suite under `tests/mcp`; extending coverage to the core
+  loop, providers, and tools is a high-value contribution.
+
+## Development setup
+
+Requires **Python 3.11+**.
+
+```bash
+git clone https://github.com/ilayanambi-ponramu/curry-leaves-py.git
+cd curry-leaves-py
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Common commands:
+
+| Command | What it does |
+|---|---|
+| `mypy src` | Strict type check — **the correctness gate** |
+| `pytest` | Run the test suite (`tests/`) |
+| `curry-leaves` | Launch the full-screen Textual TUI (needs a TTY) |
+| `curry-leaves-repl` | Launch the line REPL (works with piped input) |
+| `python3 examples/01_basic.py "..."` | Run an example end-to-end |
+
+To exercise a real turn you need a provider key:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...   # or OPENAI_API_KEY=sk-...
+curry-leaves
+```
+
+Or run fully local with [Ollama](https://ollama.com) — no key required:
+
+```bash
+ollama pull qwen3
+CURRY_LEAVES_MODEL=qwen3 curry-leaves-repl
+```
+
+> **Testing status:** `mypy src` under `strict` is the gate every change must pass, plus `pytest`
+> for the MCP suite. Providers are written so their request builders and stream parsers are plain
+> module functions (not client methods) specifically to be unit-testable — contributions that add
+> a test suite around them are especially welcome.
+
+## Project layout
+
+```
+src/curry_leaves/
+  core/        # messages, events, loop, tools, agent, host, blobs — the kernel
+  providers/   # anthropic, openai/ollama, factory, sse, base
+  tools/       # read, write, edit, find, search, bash, tasks, ask, web, …
+  mcp/         # MCP client: stdio/HTTP servers, manager, settings loader, tool adapter
+  session/     # session store + recording
+  cli/         # chat REPL + Textual TUI
+  util/        # paths, retry, frontmatter, resources
+  runner.py prompt.py permission.py thinking.py skills.py compaction.py catalog.py settings.py
+  __init__.py  # public API surface
+examples/      # runnable examples
+tests/         # pytest suite (MCP subsystem)
+```
+
+The architecture is a strict layering — a **stateless definition** (`Agent`) on a **stateful
+driver** (`Runner`) on a **pure engine** (`agent_loop`) — with all I/O pushed to swappable seams
+(`Provider`, `Host`, `Tool`). Keep that separation in mind: behavior is added at a seam, not by
+branching inside the loop. See the [README architecture section](./README.md#architecture) for the
+big picture.
+
+## Pull request workflow
+
+1. **Open an issue first** for anything non-trivial, so we can agree on scope and approach.
+2. **Fork and branch** off `main`:
+   ```bash
+   git checkout -b feat/short-description   # or fix/… , docs/… , test/…
+   ```
+3. **Make the change.** Keep the diff focused on one concern.
+4. **Verify it passes:**
+   ```bash
+   mypy src && pytest
+   ```
+   For a change with a runtime surface, also drive the affected flow (a TUI turn, an example, the
+   REPL) and confirm it behaves as intended — don't rely on typecheck alone.
+5. **Update docs** (`README.md`, code comments, `examples/`) when behavior or the public API changes.
+6. **Open a pull request** with a clear description of *what* changed and *why*. Link the issue.
+
+Keep PRs small and reviewable. A large PR is easier to land when split into focused commits or
+separate PRs.
+
+## Code conventions
+
+- **`src/curry_leaves/__init__.py` is the public API.** When you add an exported symbol consumers
+  should see, re-export it there and add it to `__all__`.
+- **Keep new source under `src/curry_leaves/`** — the package uses a `src/` layout.
+- **Match the surrounding style** — small, single-purpose modules; clear names; comments that explain
+  *why*, not *what*. Prefer boring, direct solutions.
+- **Type strictly.** `mypy --strict` is on and must stay green. No new `Any` where a real type fits;
+  public functions carry full annotations.
+- **Tools describe their `risk`** (`read` / `write` / `exec` / `network`) — it drives the permission
+  fallback, so set it accurately.
+- **Complete the change** — types, docs, and (where practical) a runnable check, not just the happy path.
+
+## Extending the kernel
+
+Common extension points, each done at a seam rather than by editing the loop:
+
+- **Add a tool** — implement the `Tool` protocol (a pydantic args model + `run`), add a factory under
+  `src/curry_leaves/tools/`, export it from `__init__.py`, and add it to a preset in `presets.py` if
+  it belongs in the default kit. Set `risk` correctly.
+- **Add a provider** — implement `Provider.stream` in `src/curry_leaves/providers/`, keep all
+  wire-format translation at that edge (nowhere else), and register it in `providers/factory.py`.
+- **Add a frontend capability** — add a `Request` kind in `src/curry_leaves/core/host.py` (with a
+  default value), **not** a new `Host` method — so headless hosts keep working by returning the
+  default.
+- **Connect an MCP server** — usually no code change needed: construct `McpServerStdio`/`McpServerHttp`
+  (or declare it in `settings.json`'s `mcpServers`) and pick tools with `mcp_tools()`. Framework-level
+  MCP changes live under `src/curry_leaves/mcp/` and are covered by `tests/mcp`.
+
+## Commit messages
+
+Use short, imperative summaries. Conventional-commit prefixes are appreciated but not required:
+
+```
+feat: add web_search deferred tool
+fix: retry only on transient provider errors
+docs: clarify Ollama setup
+test: cover the anthropic stream parser
+```
+
+## Reporting bugs
+
+Open an issue that includes:
+
+- What you did (a minimal code snippet or the exact CLI command).
+- What you expected vs. what happened (include the full error / stack).
+- Your environment: `python --version`, curry-leaves version, provider + model id, OS.
+
+A minimal reproduction is the fastest path to a fix.
+
+## License
+
+By contributing, you agree that your contributions are licensed under the project's
+[MIT License](./LICENSE).

curry_leaves-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ilayanambi Ponramu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

curry_leaves-1.0.0/PKG-INFO

@@ -0,0 +1,392 @@
+Metadata-Version: 2.4
+Name: curry-leaves
+Version: 1.0.0
+Summary: Curry Leaves — a small, provider-agnostic, multi-agent kernel for building AI agents of any kind: streaming tool-use loop, sub-agents, skills, thinking. The Python port.
+Project-URL: Homepage, https://github.com/ilayanambi-ponramu/curry-leaves-py
+Project-URL: Repository, https://github.com/ilayanambi-ponramu/curry-leaves-py
+Project-URL: Issues, https://github.com/ilayanambi-ponramu/curry-leaves-py/issues
+Project-URL: Changelog, https://github.com/ilayanambi-ponramu/curry-leaves-py/blob/main/CHANGELOG.md
+Author: Ilayanambi Ponramu
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai-agent,anthropic,coding-agent,llm,mcp,multi-agent,ollama,openai,subagents,tool-use
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.9
+Requires-Dist: pydantic>=2.7
+Requires-Dist: rich>=13.7
+Requires-Dist: textual>=0.58
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/logo.png" alt="Curry Leaves logo" width="128" height="128">
+</p>
+
+<h1 align="center">Curry Leaves Agent Loop</h1>
+
+<p align="center">A small, provider-agnostic, multi-agent kernel for building AI agents of any kind — in clean, readable Python.</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/curry-leaves/"><img src="https://img.shields.io/pypi/v/curry-leaves.svg" alt="PyPI version"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="license: MIT"></a>
+  <a href="https://www.python.org"><img src="https://img.shields.io/badge/python-%3E%3D3.11-brightgreen.svg" alt="python: >=3.11"></a>
+  <a href="./src/curry_leaves/py.typed"><img src="https://img.shields.io/badge/types-included-blue.svg" alt="types included"></a>
+  <a href="https://github.com/ilayanambi-ponramu/curry-leaves-py"><img src="https://img.shields.io/badge/github-repo-181717.svg?logo=github" alt="GitHub repo"></a>
+</p>
+
+**Curry Leaves** is a general-purpose agent kernel small enough to read in an afternoon. At its core
+is a streaming tool-use loop — call the model, run the tools it asks for, feed the results back,
+repeat — with everything a real agent needs built around it: **sub-agents**, **skills**, **MCP
+tools**, **permission gating**, **session recording**, automatic **context compaction**, and
+per-turn **reasoning-effort sizing**. Point it at any tools and any task; the kernel is
+domain-agnostic — it just happens to ship a batteries-included coding toolset and CLIs on top.
+
+One engine, any provider, any UI. The loop knows nothing about a specific LLM wire format — each
+provider translates at its own boundary — so Anthropic, OpenAI, and Ollama are a *config choice, not
+branching logic*. Use it as a **library** (below), or launch either bundled CLI: a full-screen
+terminal UI or a line REPL.
+
+```python
+from curry_leaves import Agent, Runner, coding_tools
+
+agent  = Agent(model="claude-sonnet-4-5", tools=coding_tools())
+result = await Runner(agent).run("Summarize README.md in three bullets.")
+print(result.output_text)
+```
+
+---
+
+## Table of contents
+
+- [Features](#features)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Configure a provider](#configure-a-provider)
+- [Terminal UI & REPL](#terminal-ui--repl)
+- [Library usage](#library-usage)
+- [Environment variables](#environment-variables)
+- [Architecture](#architecture)
+- [Project layout](#project-layout)
+- [Development](#development)
+- [Contributing](#contributing)
+- [Non-goals](#non-goals)
+- [Acknowledgements](#acknowledgements)
+- [License](#license)
+
+## Features
+
+- **Multi-provider.** Anthropic, OpenAI, and Ollama (any OpenAI-compatible gateway) implement one
+  `Provider.stream()` interface; the loop never changes. Streaming SSE is assembled into a neutral
+  `AssistantMessage` at the provider boundary and nowhere else.
+- **Rich toolset.** `read`, `write`, `edit`, `find`, `search`, `bash`,
+  `task_create`/`task_update`/`task_list`/`task_get`, `ask`, `current_time`, `web_fetch`,
+  `web_search`. Tool args are [pydantic](https://docs.pydantic.dev) models → JSON Schema for free.
+  Oversized output is offloaded to an artifact store the model can page through with `read`.
+- **MCP tools.** Connect any [Model Context Protocol](https://modelcontextprotocol.io) server —
+  stdio subprocess or HTTP — and pick specific tools by name with `mcp_tools()`; the result is a
+  plain `list[Tool]` spliced into `Agent(tools=[...])` like any preset. Servers can also be declared
+  in `settings.json`'s `mcpServers` key. MCP tools default to `risk="exec"`, so they always go
+  through the permission gate.
+- **Deferred tools + `search_tools`.** Keep the advertised list lean; the model discovers more
+  tools by keyword and activates them for the next turn — works across providers.
+- **Sub-agents.** Declare `subagents=[...]`; the parent gets a `task` tool (delegation that returns
+  a result) and a `transfer` tool (one-way handoff). Bounded recursion depth.
+- **Structured output.** Give an agent an `output_type` (a pydantic model); the Runner injects the
+  schema, validates the final reply, and retries on mismatch. `result.output` is typed.
+- **Auto-thinking.** `auto_thinking=True` sizes reasoning effort (Anthropic thinking budget /
+  OpenAI reasoning effort) per turn with a cheap classifier.
+- **Skills.** Drop a `SKILL.md` under `.curry-leaves/skills/<name>/`; its teaser goes into the prompt and
+  the model pulls the full body via `read skill://<name>` only when relevant (progressive disclosure).
+- **Permissions.** An opt-in gate authorizes each tool call (`allow` / `ask` / `deny`), with standing
+  approvals and contained-change auto-approval. Off by default — headless runs never hang.
+- **Sessions.** Each run can be recorded to `<home>/sessions/<id>/` (`meta.json` + `transcript.jsonl`).
+- **Compaction.** Long conversations are summarized as they near the context window — automatic, or
+  on demand via `Runner.compact()` / the `/compact` command.
+- **Typed, async, dependency-light.** Python 3.11+, `mypy --strict`, ships `py.typed`. The library
+  core rides on `pydantic` + `httpx`; the CLIs add [Textual](https://textual.textualize.io) + Rich,
+  and MCP support uses the official `mcp` SDK.
+
+## Install
+
+```bash
+pip install curry-leaves
+```
+
+Then launch a CLI:
+
+```bash
+curry-leaves        # full-screen terminal UI (alias: curry)
+curry-leaves-repl   # line REPL (works with piped input)
+```
+
+Requires **Python 3.11+**.
+
+## Quick start
+
+```python
+import asyncio
+from curry_leaves import Agent, Runner, coding_tools
+
+async def main() -> None:
+    agent = Agent(
+        model="claude-sonnet-4-5",
+        instructions="You are a concise coding assistant.",
+        tools=coding_tools(),
+    )
+    result = await Runner(agent).run("What does src/curry_leaves/runner.py do?")
+    print(result.output_text)
+
+asyncio.run(main())
+```
+
+`Agent` is a stateless **definition** (model, tools, instructions); `Runner` holds the live
+conversation and drives the streaming loop. Set an API key first (see below).
+
+## Configure a provider
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...   # or
+export OPENAI_API_KEY=sk-...
+```
+
+The provider is inferred from the model id (`claude-*` → Anthropic, `gpt-*`/`o1-*` → OpenAI,
+`gemma*`/`llama*`/`qwen*`/… → Ollama), or set `CURRY_LEAVES_PROVIDER` / pass an explicit `provider`
+to the `Agent`.
+
+### Local models via Ollama
+
+Ollama speaks the OpenAI wire format, so any pulled tag works with no API key:
+
+```bash
+ollama pull qwen3
+CURRY_LEAVES_MODEL=qwen3 curry-leaves-repl
+```
+
+```python
+from curry_leaves import Agent, Runner, coding_tools
+agent = Agent(model="qwen3", tools=coding_tools())   # provider → Ollama
+```
+
+Set `OLLAMA_HOST` to point at a non-default server (`http://host:port`). Tool use needs a model with
+the `tools` capability (qwen3, llama3.x, gemma3, …). Reasoning-effort knobs are dropped for Ollama,
+and usage cost is `$0` (local). You can point the same `OpenAIProvider` at any OpenAI-compatible
+gateway via `OPENAI_BASE_URL` or explicit provider options.
+
+## Terminal UI & REPL
+
+A full-screen terminal UI (built on [Textual](https://textual.textualize.io)) ships with the
+package — a header bar, a streaming transcript, live thinking blocks, spinner-tracked tool calls,
+indented sub-agent activity, a status bar, and a persistent input box. Finished turns land in real
+terminal scrollback; the active turn streams in place.
+
+```bash
+curry-leaves
+```
+
+```
+╭──────────────────────────────────────────────────────────╮
+│ curry-leaves · claude-sonnet-4-5 (anthropic)             │
+│ /repo · 11 tools · subagents: explore, plan              │
+╰──────────────────────────────────────────────────────────╯
+
+you › what does src/curry_leaves/runner.py do?
+ai ›
+  → read({"path":"src/curry_leaves/runner.py"})
+      1  """The Runner — holds one live conversation … """
+The Runner composes an Agent with conversation state and drives the loop …
+
+ ● ready                                    in 4213 · out 187 · $0.0155
+╭──────────────────────────────────────────────────────────╮
+│ › ask anything — /help for commands                      │
+╰──────────────────────────────────────────────────────────╯
+```
+
+**Slash commands:** `/help`, `/reset`, `/tools`, `/skills`, `/model`, `/stats`, `/clear`,
+`/compact [focus]`, `/auto` (toggle contained-change auto-approve), `/autonomous` (toggle self-drive
+mode), `/exit`. The TUI needs an interactive terminal (a TTY).
+
+The line-streaming REPL is available as `curry-leaves-repl` — handy for piped / non-TTY input.
+
+## Library usage
+
+### Stream events instead of awaiting
+
+```python
+async for event in runner.stream("Refactor the parser"):
+    if event.type == "message_update" and event.delta and event.delta.kind == "text":
+        print(event.delta.value, end="", flush=True)
+```
+
+### Structured output
+
+```python
+import pydantic
+from curry_leaves import Agent, Runner
+
+class Summary(pydantic.BaseModel):
+    title: str
+    bullets: list[str]
+
+agent = Agent(model="claude-sonnet-4-5", output_type=Summary)
+
+result = await Runner(agent).run("Summarize this repo.")
+report = result.output   # validated Summary instance; the Runner retries on a schema mismatch
+```
+
+### Sub-agents
+
+```python
+from curry_leaves import Agent, Runner, coding_tools, explore_agent, plan_agent
+
+agent = Agent(
+    model="claude-sonnet-4-5",
+    tools=coding_tools(),
+    subagents=[explore_agent("claude-sonnet-4-5"), plan_agent("claude-sonnet-4-5")],
+)
+# The parent can `task` (delegate → result) or `transfer` (one-way handoff) to these.
+```
+
+### MCP tools
+
+```python
+from curry_leaves import Agent, Runner, coding_tools
+from curry_leaves.mcp import McpServerStdio, mcp_tools
+
+async with McpServerStdio(name="github", command="npx", args=["-y", "@modelcontextprotocol/server-github"]) as gh:
+    agent = Agent(
+        model="claude-sonnet-4-5",
+        tools=[*coding_tools(), *await mcp_tools(gh, "search_issues")],
+    )
+    result = await Runner(agent).run("Find open issues about streaming.")
+```
+
+Or declare servers once in `.curry-leaves/settings.json` under `mcpServers` and load them with
+`load_mcp_servers()` + `McpServerManager`. See
+[`examples/07_mcp_tools.py`](examples/07_mcp_tools.py) for a complete, self-contained program.
+
+See [`examples/01_basic.py`](examples/01_basic.py) for the smallest runnable program, and
+[`examples/06_host_and_permissions.py`](examples/06_host_and_permissions.py) for a self-contained
+illustration of the host / permission model.
+
+## Environment variables
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `ANTHROPIC_API_KEY` | Anthropic auth | — |
+| `OPENAI_API_KEY` | OpenAI auth | — |
+| `CURRY_LEAVES_MODEL` | Model id for the CLIs | auto-detected |
+| `CURRY_LEAVES_PROVIDER` | Force a provider (`anthropic` \| `openai` \| `ollama`) | inferred from model id |
+| `CURRY_LEAVES_HOME` | Base dir for settings / skills / sessions | `~/.curry-leaves` |
+| `CURRY_LEAVES_NO_RECORD` | Disable session recording when set | recording on |
+| `OPENAI_BASE_URL` | Point `OpenAIProvider` at any OpenAI-compatible gateway | `https://api.openai.com/v1` |
+| `OLLAMA_HOST` | Ollama server URL | `http://localhost:11434` |
+| `NO_COLOR` | Disable ANSI color | color on |
+
+## Architecture
+
+The design is a strict layering — a **stateless definition** on a **stateful driver** on a **pure
+engine** — with all I/O pushed to swappable seams (Provider, Host, Tool).
+
+| Layer | File | Responsibility |
+|---|---|---|
+| **Message model** | `core/messages.py` | Provider-neutral `Message`/`Content` types — the one thing everything agrees on. |
+| **Events** | `core/events.py` | What the loop yields; a small structural set + a streaming `delta` payload. |
+| **Loop** | `core/loop.py` | The pure engine: `stream → run tools → stream`, while tools are called. Yields events. |
+| **Tools** | `core/tools.py` | A registry of pydantic-typed tools + a concurrent executor with a universal large-result guard. |
+| **Agent** | `core/agent.py` | A stateless definition (model, tools, instructions, sub-agents, `output_type`). |
+| **Runner** | `runner.py` | Live conversation state; builds the `Context` each turn; wires sub-agents, handoff, permissions, compaction. |
+| **Providers** | `providers/*` | The only place that knows a wire format. Anthropic / OpenAI / Ollama behind one `Provider`. |
+| **MCP** | `mcp/*` | MCP client: stdio/HTTP server connections, a manager, a settings loader, and a tool adapter. |
+| **Host** | `core/host.py` | The frontend seam: `emit(event)` + `request(req)`. Headless by default. |
+| **Prompt** | `prompt.py` | Layered system prompt (identity → instructions → env → context → tools), cache-friendly. |
+| **Permission** | `permission.py` | Per-call `allow` / `ask` / `deny` gate with standing approvals. |
+| **Thinking** | `thinking.py` | A tiny classifier that sizes reasoning effort per task. |
+| **Skills** | `skills.py` | Progressive-disclosure capability packages via `skill://` refs. |
+| **Compaction** | `compaction.py` | Summarizes old history as the context window fills. |
+
+The one decision that drives the whole loop:
+
+```
+runnable = stop_reason in ("tool_use", "stop") AND tool_calls exist
+```
+
+Tools were called → loop again. None → stop.
+
+## Project layout
+
+```
+src/curry_leaves/
+  core/        # messages, events, loop, tools, agent, host, blobs — the kernel
+  providers/   # anthropic, openai/ollama, factory, sse, base
+  tools/       # read, write, edit, find, search, bash, tasks, ask, web, …
+  mcp/         # MCP client: servers, manager, config, tool adapter
+  session/     # session store + recording
+  cli/         # chat REPL + Textual TUI
+  util/        # paths, retry, frontmatter, resources
+  runner.py prompt.py permission.py thinking.py skills.py compaction.py catalog.py settings.py
+  __init__.py  # public API surface
+examples/      # runnable examples
+tests/         # pytest suite (MCP subsystem)
+```
+
+## Development
+
+```bash
+git clone https://github.com/ilayanambi-ponramu/curry-leaves-py.git
+cd curry-leaves-py
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+mypy src               # strict type check (the correctness gate)
+pytest                 # run the test suite
+curry-leaves           # launch the Textual TUI (needs a TTY)
+curry-leaves-repl      # launch the REPL (works with piped input)
+python3 examples/01_basic.py "What is this project?"
+```
+
+`mypy --strict` is the gate every change must pass; `pytest` covers the MCP subsystem.
+Contributions extending the test suite are welcome.
+
+## Contributing
+
+Contributions are very welcome — bug reports, features, docs, and tests. In short:
+
+1. **Open an issue first** for anything non-trivial, so we can agree on the approach.
+2. **Fork & branch** off `main` (`git checkout -b feat/short-description`).
+3. **Make the change**, keep the diff focused, and ensure `mypy src` and `pytest` pass.
+4. **Open a pull request** describing the what and why.
+
+See **[CONTRIBUTING.md](./CONTRIBUTING.md)** for the full guide — dev setup, code conventions, how to
+add a tool / provider / frontend capability, commit style, and bug-reporting.
+
+## Non-goals
+
+curry-leaves is deliberately small. It does **not** include LSP integration, vector stores, or a
+plugin marketplace. If you need those, they belong in a layer built on top of the kernel, not inside
+it. (Unlike the TypeScript sibling, MCP *is* included here — as a thin client layer that feeds the
+existing `Tool` seam, not a change to the kernel.)
+
+## Acknowledgements
+
+curry-leaves for Python is the sibling of
+[curry-leaves-ts](https://github.com/ilayanambi-ponramu/curry-leaves-ts), a TypeScript kernel of the
+same design; the two ports mirror each other module-for-module.
+
+## License
+
+[MIT](./LICENSE) © Ilayanambi Ponramu