Metadata-Version: 2.4
Name: kunchi
Version: 0.1.0
Summary: A simple coding harness with planner-implementor-validator orchestration
Project-URL: Homepage, https://github.com/Hudsone/kunchi
Project-URL: Repository, https://github.com/Hudsone/kunchi
Project-URL: Issues, https://github.com/Hudsone/kunchi/issues
Project-URL: Documentation, https://github.com/Hudsone/kunchi/blob/main/docs/ROADMAP.md
Author-email: Hsiwei Chang <hudsone@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: coding-agent,cursor,harness,orchestration
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Build Tools
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: pyyaml>=6.0; extra == 'dev'
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == 'yaml'
Description-Content-Type: text/markdown

# kunchi
A Simple Coding Harness (Python)

Multi-agent orchestration: planner → implementor → sequential validators, with output contracts and retry loops.

## Quick start

```bash
pip install kunchi
# or for development:
pip install -e ".[dev]"
pytest
python3 -m kunchi.examples.demo "Build a demo feature"
```

The demo uses **fake agents** (no external CLIs) to exercise the full harness flow.

### CLI (recommended for real repos)

```bash
pip install -e ".[dev]"
cd /path/to/your/repo
kunchi init --template cursor    # writes .kunchi/profile.yaml
export CURSOR_API_KEY=...        # for cursor template
kunchi run "Your goal"
kunchi run "Your goal" --monitor   # compact progress lines on stderr
kunchi run "Your goal" --trace      # verbose debug trace on stdout
kunchi plans
kunchi resume PLAN_ID
```

Use `kunchi init --template fake` to try the flow without Cursor. See [docs/ROADMAP.md](docs/ROADMAP.md#good-enough-to-start).

See [docs/MANUAL_TESTING.md](docs/MANUAL_TESTING.md) for manual smoke tests. Development progress and a **good enough to start** checklist are in [docs/ROADMAP.md](docs/ROADMAP.md#good-enough-to-start). Runnable scripts are in `src/kunchi/examples/manual/`:

```bash
python3 -m kunchi.examples.manual.harness_fake
python3 -m kunchi.examples.manual.cli_runner
python3 -m kunchi.examples.manual.cli_agent_fake_binary
```

## hello()

`kunchi` exports a small public `hello()` helper (see `src/kunchi/hello.py`). It returns the string `"hello"`.

```python
from kunchi import hello

hello()  # "hello"
```

## Agent backends

**Fake agents** (default) — no external dependencies:

```python
from kunchi import Harness, default_harness_config

harness = Harness(default_harness_config())
```

**Cursor CLI** — requires the `agent` binary on PATH; tasks require `summary` + `git_commit` and run `ruff` / `pytest` shell validators before Cursor review:

```python
from kunchi.harness import Harness, default_cursor_harness_config

harness = Harness(default_cursor_harness_config(workspace_path="/path/to/repo"))
```

Profiles bundle fixed output contracts and validators; register custom ones or load from a dict:

```python
from kunchi.harness import harness_config_from_profile
from kunchi.profiles import ProfileRegistry, load_profile

harness = Harness(harness_config_from_profile("cursor", "/path/to/repo"))

# Dynamic / file-based (same shape a planner could emit later):
from pathlib import Path

from kunchi.harness import harness_config_from_profile_file
from kunchi.profiles import ProfileRegistry, load_profile, load_profile_file

harness = Harness(harness_config_from_profile("cursor", "/path/to/repo"))

profile = load_profile_file(Path("my-profile.json"))
registry = ProfileRegistry.default()
registry.register(profile)
harness = Harness(harness_config_from_profile(profile.name, ".", registry=registry))

# Or in one step:
harness = Harness(harness_config_from_profile_file("my-profile.yaml", "/path/to/repo"))
```

Or configure agents explicitly:

```python
from kunchi import Harness, HarnessConfig
from kunchi.models.agent import AgentRole, AgentSpec
from kunchi.models.context import WorkspaceConfig

config = HarnessConfig(
    planner=AgentSpec(id="planner", role=AgentRole.PLANNER, config={"cli": "cursor"}),
    workspace=WorkspaceConfig(path="."),
    default_validators=[
        AgentSpec(id="lint", role=AgentRole.VALIDATOR, config={"cli": "shell", "command": "ruff check ."}),
    ],
)
harness = Harness(config)
```

## Extending integrations

External system adapters live under `src/kunchi/providers/`:

- **Agent clients** (`providers/agents/`) — implement `AgentClient` and register in `AgentClientRegistry` (Cursor is built in)
- **VCS backends** (`providers/vcs/`) — implement `VCSBackend` and register in `VCSRegistry` (git is built in; hg is stubbed)

See [docs/DESIGN.md](docs/DESIGN.md) sections 9 and 17 for details.

Persist plan state to disk (resume / inspect after a run):

```python
from kunchi import Harness, default_harness_config
from kunchi.state import FilePlanStore

harness = Harness(default_harness_config(), plan_store=FilePlanStore(".kunchi/plans"))
report = await harness.run("Build feature")

# After an interrupt or partial run, continue from persisted state:
report = await harness.resume(report.plan_id)

# List saved plans:
summaries = await harness.list_plans()
```

