Metadata-Version: 2.4
Name: kerf
Version: 0.1.0
Summary: Declarative workflow engine where the LLM is a pluggable, disposable step
Project-URL: Homepage, https://github.com/derek-yn-zhang/kerf
Project-URL: Documentation, https://derek-yn-zhang.github.io/kerf/
Project-URL: Repository, https://github.com/derek-yn-zhang/kerf
Project-URL: Issues, https://github.com/derek-yn-zhang/kerf/issues
Author: Derek Zhang
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: fastapi>=0.100
Requires-Dist: pydantic>=2.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: uvicorn>=0.23
Provides-Extra: dev
Requires-Dist: httpx>=0.24; extra == 'dev'
Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <strong>Kerf</strong><br>
  Declarative workflow engine for Claude CLI
</p>

---

Kerf runs deterministic tools first, calls the LLM only when you need reasoning, and logs every result. Pipelines are defined as JSON — no Python required to configure a workflow.

- **Deterministic-first** — preprocessing runs without the LLM until you actually need it
- **JSON workflows** — define tool chains, prompt templates, and fallback policies as config
- **Per-workflow fallback** — `retry` the LLM, degrade to `deterministic` output, or `flag` for review
- **Full execution logging** — every run gets a UUID-stamped log you can audit and learn from
- **Auto-discovered tools** — drop a Python file in `tools/`, it gets picked up

## Install

```bash
uv tool install kerf
```

Requires Python 3.10+ and Claude CLI (`claude login`).

## Quick Start

```bash
kerf init
```

```
Kerf project initialized.
```

```bash
kerf run summarize "Kerf is a workflow engine that wraps Claude CLI..."
```

```json
{
  "summary": "Kerf is a declarative workflow engine that wraps Claude CLI for structured, deterministic text processing."
}
```

A workflow is a JSON file in `workflows/`:

```json
{
  "task_type": "summarization",
  "tool_chain": [{ "tool": "normalize_text", "condition": "always_true" }],
  "fallback": "retry"
}
```

`tool_chain` runs deterministic preprocessing. `task_type` sends the result to Claude. `fallback` controls what happens when the LLM fails.

Custom tools go in `tools/` as Python files with a `register(manager)` function:

```python
# tools/uppercase.py
def uppercase(input_data, params):
    return input_data.upper()

def register(manager):
    manager.register_tool("uppercase", uppercase)
```

## Documentation

Full docs at [derek-yn-zhang.github.io/kerf](https://derek-yn-zhang.github.io/kerf/).

## License

MIT
