kerf 0.1.0__tar.gz

kerf-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,33 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install mkdocs-material
+      - run: mkdocs build
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+      - id: deployment
+        uses: actions/deploy-pages@v4

kerf-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/kerf
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

kerf-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,20 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest

kerf-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+.venv/
+
+# uv
+uv.lock
+
+# OS
+.DS_Store
+
+# IDE
+.vscode/
+.idea/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Kerf project artifacts (for testing)
+logs/
+.kerf

kerf-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+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

kerf-0.1.0/README.md

@@ -0,0 +1,73 @@
+<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

kerf-0.1.0/docs/concepts/design-decisions.md

@@ -0,0 +1,40 @@
+# Design Decisions
+
+## Why subprocess, not SDK?
+
+Kerf shells out to the Claude CLI (`claude -p`) rather than using Anthropic's Python SDK. This means:
+
+- It works with whatever authentication the CLI provides, including Max Plan
+- No API keys to manage
+- No dependency on Anthropic's SDK versioning
+- The CLI handles model selection, rate limiting, and context management
+
+The tradeoff is latency — spawning a subprocess is slower than an HTTP call. But the LLM call itself dominates the total time, so the subprocess overhead is negligible.
+
+## Why sync, not async?
+
+The engine is synchronous. `subprocess.run` and file I/O are blocking operations. There's no benefit to async here — the bottleneck is the LLM call, and you can't parallelize a single CLI invocation.
+
+The FastAPI server handles concurrency at the request level. When you define the endpoint as a regular `def` (not `async def`), FastAPI runs each request in a thread pool automatically.
+
+## Why named conditions instead of expressions?
+
+Workflow files are JSON. If conditions were inline expressions like `"len(input) > 500"`, you'd need either an expression parser or `eval()`. Both are worse than a simple name-to-function registry:
+
+- `eval()` is a security risk
+- Expression parsers add complexity for marginal benefit
+- Named conditions are explicit, debuggable, and inspectable
+- You can set breakpoints in condition functions
+
+The cost is that you have to write a Python function and register it. The benefit is that your workflow files stay data — no code in config.
+
+## Why JSON workflows, not Python?
+
+Python workflow definitions would be more expressive, but JSON workflows are:
+
+- Editable by anyone, even people who don't write Python
+- Serializable and transferable — you can store them in a database, send them over HTTP, version them in git
+- Inspectable — `kerf list` can read them without importing any code
+- Constrained — they can't do anything surprising
+
+The tool chain is where Python lives. The workflow file is where configuration lives. Keeping them separate means you can change pipeline behavior without touching code.

kerf-0.1.0/docs/concepts/engine.md

@@ -0,0 +1,52 @@
+# How the Engine Works
+
+Kerf is a thin orchestration layer over the Claude CLI. It doesn't embed a model, manage API keys, or do anything clever with tokens. It wraps `claude -p --output-format json` in a structured pipeline and adds the scaffolding to make LLM calls reproducible, validatable, and replaceable.
+
+## Pipeline
+
+Every workflow execution follows the same sequence:
+
+```
+input_data
+  |
+  v
+[tool_chain: deterministic preprocessing]
+  |
+  v
+[LLM call via Claude CLI (optional)]
+  |
+  v
+[schema validation → fallback if needed]
+  |
+  v
+result (LLM output or tool output)
+  |
+  v
+[logged to logs/<uuid>.json]
+```
+
+1. Load workflow config from `workflows/<name>.json`
+2. Set up the tool manager — register builtins, then load user tools from `tools/`
+3. Run the deterministic tool chain on the input
+4. If `task_type` is set, construct a prompt and call the LLM via Claude CLI
+5. If a `schema_path` is set, validate the LLM output — check that all required keys are present
+6. On validation failure, apply the fallback policy
+7. Log the full result to `logs/<uuid>.json`
+
+## Components
+
+**GARInterface** wraps the Claude CLI's headless mode (GAR = Generate, Analyze, Return). It checks that `claude` is on your PATH, calls `claude -p <prompt> --output-format json`, and parses the JSON response. Claude CLI handles its own authentication — Kerf doesn't manage credentials.
+
+**LocalToolManager** is a registry for deterministic tools and named conditions. Tools and conditions are registered by name (strings), not as lambdas. The workflow JSON references these names, and the manager resolves them at runtime. This is what keeps workflows fully serializable.
+
+**Engine** is the `execute_workflow()` function that ties it together. Both `kerf run` and `POST /execute` call the same function — there's no separate CLI vs server path.
+
+## Tool resolution order
+
+1. Built-in tools and conditions register first (`normalize_text`, `route_by_length`, `always_true`)
+2. User tools from `tools/` register second
+3. User tools can override builtins by registering the same name
+
+## Project detection
+
+Kerf walks up from the current working directory looking for a `.kerf` marker file, the same way git looks for `.git/`. This means you can run `kerf run` from any subdirectory of your project.

kerf-0.1.0/docs/concepts/fallback-policies.md

@@ -0,0 +1,30 @@
+# Fallback Policies
+
+Each workflow declares how much it trusts the LLM. The `fallback` field controls what happens when the LLM call fails or returns output that doesn't match the schema.
+
+## Policies
+
+| Policy | What happens | When to use it |
+|---|---|---|
+| `retry` | Call the LLM again | Tasks like summarization where there's no good deterministic alternative — just try again |
+| `deterministic` | Skip the LLM, return the preprocessed output | Tasks like classification where the LLM is flaky — fall back to whatever the tool chain produced |
+| `flag` | Return the error in the output | Ambiguous cases — log the failure, deal with it later |
+
+## When fallback triggers
+
+Fallback triggers in two situations:
+
+1. **The LLM call fails** — Claude CLI returns a non-zero exit code, or the output isn't valid JSON
+2. **Schema validation fails** — the LLM returned JSON, but it's missing required keys defined in `schema_path`
+
+The schema check is the confidence gate. If you asked the LLM to return `{"category": "..."}` and it returned `{"label": "..."}`, it didn't follow instructions. The fallback kicks in.
+
+## Choosing a policy
+
+The right policy depends on whether a deterministic alternative exists:
+
+- **Summarization** has no good deterministic fallback. If the LLM fails, `retry` is the best option.
+- **Classification** often has a rules-based fallback. Use `deterministic` to degrade gracefully.
+- **Ambiguous extractions** where you're not sure what the right answer is — use `flag` to log the failure and review manually.
+
+The policy is per-workflow, so you tune trust on a per-task basis. A workflow that's been running reliably for weeks might use `retry`. A new workflow you're still tuning might use `flag` until you've seen enough logs to trust it.

kerf-0.1.0/docs/getting-started/installation.md

@@ -0,0 +1,50 @@
+# Installation
+
+## Prerequisites
+
+- Python 3.10+
+- [Claude CLI](https://docs.anthropic.com/en/docs/claude-code) — run `claude login` to authenticate
+- [uv](https://docs.astral.sh/uv/) (recommended) or pipx
+
+Kerf calls Claude CLI under the hood. If you see `"Claude CLI not found on PATH"`, install [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and run `claude login` to authenticate.
+
+## Install
+
+```bash
+uv tool install kerf
+```
+
+Or with pipx:
+
+```bash
+pipx install kerf
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/yourusername/kerf.git
+cd kerf
+uv tool install .
+```
+
+Verify the installation:
+
+```bash
+kerf --help
+```
+
+```
+Usage: kerf [OPTIONS] COMMAND [ARGS]...
+
+  Kerf — declarative workflow engine where the LLM is a pluggable,
+  disposable step.
+
+Commands:
+  add    Add a new workflow, tool, or MCP config.
+  init   Scaffold a new kerf project in the current directory.
+  list   List available workflows and tools.
+  logs   View recent execution logs.
+  run    Execute a workflow.
+  serve  Start the Kerf API server.
+```

kerf-0.1.0/docs/getting-started/project-structure.md

@@ -0,0 +1,41 @@
+# Project Structure
+
+After running `kerf init`, your project looks like this:
+
+```
+my-pipeline/
+  .kerf                  # project marker
+  workflows/
+    summarize.json         # summarization example
+    classify.json          # classification example
+    extract.json           # structured extraction example
+  schemas/
+  tools/                   # your custom tool files go here
+  logs/
+  kerf.toml              # project config
+```
+
+## Directories
+
+**`workflows/`** — JSON files that define pipelines. Each file is a workflow you can run by name. See [Workflow Format](../reference/workflow-format.md).
+
+**`tools/`** — Python files with deterministic tool functions. Any `.py` file that exports a `register(manager)` function gets auto-loaded. See [Writing Tools](../guides/tools.md).
+
+**`schemas/`** — JSON schema files for validating LLM output. Referenced by `schema_path` in workflow configs.
+
+**`logs/`** — Execution logs. Each run creates a UUID-stamped JSON file with the full input/output record.
+
+## Files
+
+**`.kerf`** — Marker file that identifies the project root. Kerf walks up from your current directory looking for this file (like `.git`), so you can run commands from subdirectories.
+
+**`kerf.toml`** — Optional project-level configuration:
+
+```toml
+# [server]
+# host = "0.0.0.0"
+# port = 8000
+
+# [defaults]
+# fallback = "retry"
+```

kerf-0.1.0/docs/getting-started/quickstart.md

@@ -0,0 +1,101 @@
+# Quickstart
+
+This walks through scaffolding a project, running a workflow, and reading the output. Takes about 2 minutes.
+
+## Prerequisites
+
+Kerf calls [Claude Code](https://docs.anthropic.com/en/docs/claude-code) under the hood. Make sure it's installed and authenticated:
+
+```bash
+claude --version
+```
+
+If that fails, [install Claude Code](https://docs.anthropic.com/en/docs/claude-code) first. Then authenticate:
+
+```bash
+claude login
+```
+
+If `kerf run` fails with `"Claude CLI not found on PATH"`, you need to install Claude Code first.
+
+## Create a project
+
+```bash
+mkdir my-pipeline && cd my-pipeline
+kerf init
+```
+
+This creates the standard project structure with three example workflows. See [Project Structure](project-structure.md) for details.
+
+## Run the example workflows
+
+The scaffolded project includes `summarize`, `classify`, and `extract` workflows:
+
+```bash
+kerf run summarize "The quarterly earnings report showed revenue growth of 15%, driven by enterprise expansion and strong retention."
+```
+
+```json
+{
+  "summary": "Quarterly revenue grew 15% YoY, driven by enterprise expansion and strong retention."
+}
+```
+
+```bash
+kerf run classify "The login page crashes when I enter my email with a + sign"
+```
+
+```json
+{
+  "category": "bug",
+  "confidence": "high"
+}
+```
+
+```bash
+kerf run extract "Hi, I'm Sarah Chen (sarah@acme.co), VP of Engineering at Acme Corp."
+```
+
+```json
+{
+  "name": "Sarah Chen",
+  "email": "sarah@acme.co",
+  "company": "Acme Corp",
+  "role": "VP of Engineering"
+}
+```
+
+You can also pipe input from stdin:
+
+```bash
+cat article.txt | kerf run summarize
+```
+
+## Check the logs
+
+```bash
+kerf logs --last 1
+```
+
+```json
+{
+  "workflow": "summarize",
+  "timestamp": "2025-01-15T14:32:01+00:00",
+  "input_preview": "The quarterly earnings report showed...",
+  "task_type": "summarization",
+  "tool_chain": ["normalize_text"],
+  "fallback_policy": "retry",
+  "fallback_triggered": false,
+  "preprocessed": "the quarterly earnings report showed...",
+  "result": { "summary": "..." }
+}
+```
+
+Every execution is logged with a UUID filename in `logs/`. The user-facing output is just the `result` — the log captures the full pipeline breakdown for debugging and pattern extraction.
+
+## What's next
+
+- [Writing Workflows](../guides/workflows.md) — create your own pipelines
+- [Writing Tools](../guides/tools.md) — add custom preprocessing steps
+- [Reading Logs](../guides/logs.md) — audit execution results and extract patterns
+- [Using the API Server](../guides/server.md) — run workflows over HTTP

kerf-0.1.0/docs/guides/logs.md

@@ -0,0 +1,59 @@
+# Reading Logs
+
+Every workflow execution creates a log file in `logs/`. Each file is named with a UUID and contains the full execution record.
+
+## View recent logs
+
+```bash
+kerf logs
+```
+
+```json
+{
+  "workflow": "summarize",
+  "timestamp": "2025-01-15T14:32:01+00:00",
+  "input_preview": "The quarterly earnings report showed...",
+  "task_type": "summarization",
+  "tool_chain": ["normalize_text"],
+  "fallback_policy": "retry",
+  "fallback_triggered": false,
+  "preprocessed": "the quarterly earnings report showed...",
+  "result": { "summary": "..." }
+}
+```
+
+## Filter and limit
+
+```bash
+kerf logs --last 5                  # show 5 most recent
+kerf logs --workflow summarize      # filter by workflow name
+kerf logs --last 3 --workflow classify
+```
+
+## Log format
+
+Each log file is a JSON object:
+
+| Field | Description |
+|---|---|
+| `workflow` | Name of the workflow that ran |
+| `timestamp` | ISO 8601 UTC timestamp |
+| `input_preview` | First 200 characters of the raw input |
+| `task_type` | Prompt template used (or `null` for tool-only workflows) |
+| `tool_chain` | List of tool names that ran in the preprocessing step |
+| `fallback_policy` | Which fallback policy was configured |
+| `fallback_triggered` | `true` if the LLM call failed and fallback was used |
+| `preprocessed` | Output after the tool chain ran (before LLM) |
+| `result` | The final result returned to the user |
+
+## Why logging matters
+
+Logs are how you move away from LLM dependence. The workflow:
+
+1. Run a workflow against real inputs
+2. Read the logs — look at what the LLM actually returned
+3. Spot the pattern — does it always do the same transformation?
+4. Write a tool that does the same thing deterministically
+5. Remove the `task_type` from the workflow — no more LLM call
+
+The LLM is scaffolding. The logs are how you learn to remove it.