kunchi 0.1.0__tar.gz

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

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade hatch
+
+      - name: Run tests
+        run: |
+          pip install -e ".[dev]"
+          pytest
+
+      - name: Build package
+        run: hatch build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

kunchi-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+dist/
+build/

kunchi-0.1.0/.kunchi/config.yaml.example

@@ -0,0 +1,3 @@
+# Optional Kunchi project overrides.
+# profile: profile.yaml
+# plan_store: plans

kunchi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hsiwei Chang
+
+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.

kunchi-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+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()
+```
+

kunchi-0.1.0/README.md

@@ -0,0 +1,136 @@
+# 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()
+```
+