Skip to content

fix(packaging): bundle roles/ inside the wheel + add bundled: prefix (-> v1.1.2)#40

Merged
Protocol-zero-0 merged 1 commit into
mainfrom
fix/bundle-roles-in-wheel
May 26, 2026
Merged

fix(packaging): bundle roles/ inside the wheel + add bundled: prefix (-> v1.1.2)#40
Protocol-zero-0 merged 1 commit into
mainfrom
fix/bundle-roles-in-wheel

Conversation

@Protocol-zero-0

Copy link
Copy Markdown
Owner

Why

Reference role scripts (planner.py, executor.sh, evaluator.py, goal_evaluator.py, strategist.py) lived at the repo top level, so pip install evolution-kernel users got the runtime but no working executor — the README's

```yaml
roles:
planner: ["python3", "roles/planner.py"]
```

only resolved for git-clone users whose CWD was the repo root. Worse, the v1.1.1 --permission-mode bypassPermissions fix lived in a file pip users didn't have.

What changes

  • Move roles/*evolution_kernel/roles/* so setuptools bundles them as package_data.
  • Add evolution_kernel/_bundled.py with resolve_bundled(arg) using importlib.resources.
  • Teach config._parse_roles to resolve a new bundled:<filename> prefix to the installed absolute path. bundled:executor.sh works whether the user pip install-ed or git clone-ed.
  • Update 5 templates + examples/evolution.yml + both READMEs (EN + ZH) to use bundled: form. evolution-kernel init now writes a config that runs out of the box on pip-installed boxes.
  • Add 6 tests covering happy-path resolution, no-op on plain argv, path-separator rejection, missing-file errors, and end-to-end through load_config.
  • Bump pyproject.toml 1.1.1 → 1.1.2.

Backward compatibility

  • bundled: is opt-in. Plain argv (["python3", "myplanner.py"]) passes through unchanged.
  • Existing configs that hardcoded roles/X at the repo top level will need updating to bundled:X (or to the new path evolution_kernel/roles/X). The audience for this is very small in v1.1 — the README and evolution-kernel init templates are already updated, so a fresh checkout / fresh init "just works."

Verification

  • python -m unittest discover -s tests108 tests pass (102 prior + 6 new)
  • python -m build — wheel now contains evolution_kernel/roles/{evaluator.py,executor.sh,goal_evaluator.py,planner.py,strategist.py}
  • Fresh venv pip install ...whlresolve_bundled("bundled:executor.sh") returns a real site-packages path that exists
  • CI green on this PR

What this unblocks

  • Closes the v1.1.1 release-notes gap where the fix was advertised but pip users had no executor file to apply it to.
  • Pre-requisite for v1.2.0 publicize narrative — pip install evolution-kernel + evolution-kernel init is now a self-contained 30-second flow.

Reference role scripts (planner, executor, evaluator, goal_evaluator,
strategist) lived at the repo top level, so `pip install evolution-kernel`
gave users the runtime but no working executor — the README's
`["python3", "roles/planner.py"]` only resolved for git-clone users with
the repo as their CWD.

This change moves `roles/` into `evolution_kernel/roles/` so setuptools
ships them as `package_data`, then teaches `config._parse_roles` to
resolve a new `bundled:<name>` prefix to the installed absolute path via
`importlib.resources`. The same `evolution.yml` now works for both
`pip install` users and developers running from a checkout.

What changed
- Move 5 role files: roles/* -> evolution_kernel/roles/*
- pyproject.toml: package-data adds `roles/*`
- evolution_kernel/_bundled.py: resolve_bundled() helper using importlib.resources
- config.py: _parse_roles applies resolve_bundled to each argv entry; FileNotFoundError / ValueError surface as ConfigError
- 5 templates (lint / coverage / perf / benchmark / custom): roles/X.py -> bundled:X.py
- examples/evolution.yml: same swap + comment refresh
- README.md + README.zh.md: both quickstart and config-reference snippets updated; project-layout note refreshed
- tests/test_bundled_roles.py: 6 new tests covering happy path, no-op for plain argv, path-separator rejection, missing-file errors, and end-to-end through load_config

Backward compat
- bundled: prefix is opt-in. Plain argv (e.g. `["python3", "myplanner.py"]`)
  passes through resolve_bundled unchanged.
- Existing configs that hardcoded `roles/X` at the repo top level WILL
  need updating to `bundled:X` (or to the new `evolution_kernel/roles/X`
  path). Per the v1.1 publicize narrative this audience is very small —
  the README and `evolution-kernel init` templates are already updated.

Tests
- 108 tests pass (102 prior + 6 new bundled-role tests)
- End-to-end smoke: fresh venv `pip install dist/...whl` + resolve_bundled
  returns site-packages absolute paths for all 5 role files

Bump
- pyproject.toml: 1.1.1 -> 1.1.2
Copilot AI review requested due to automatic review settings May 26, 2026 10:05
@Protocol-zero-0 Protocol-zero-0 merged commit 5dfef32 into main May 26, 2026
6 checks passed
@Protocol-zero-0 Protocol-zero-0 deleted the fix/bundle-roles-in-wheel branch May 26, 2026 10:08

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR fixes packaging/runtime usability for pip install evolution-kernel by bundling the reference role scripts inside the Python wheel and introducing a bundled:<filename> config prefix that resolves to the installed on-disk role path via importlib.resources. This makes evolution-kernel init templates and example configs runnable without requiring a repo-root CWD or a git clone.

Changes:

  • Added evolution_kernel/_bundled.py and updated config._parse_roles to resolve bundled:<filename> argv entries to installed evolution_kernel/roles/<filename> paths (with validation + clearer config errors).
  • Moved/added bundled role scripts under evolution_kernel/roles/ and ensured they’re included in the wheel via pyproject.toml package-data.
  • Updated templates/examples/READMEs to use bundled: and added unit tests covering resolution and error cases.

Reviewed changes

Copilot reviewed 15 out of 18 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
tests/test_bundled_roles.py Adds tests for bundled: resolution behavior and error surfacing through load_config.
README.md Updates configuration examples/docs to use bundled: and describes bundled role locations.
README.zh.md Same as README.md but for the Chinese documentation.
pyproject.toml Bumps version to 1.1.2 and includes evolution_kernel/roles/* as package data.
examples/oss_fix_demo/bots/executor.py Updates docs to reference the new bundled executor path.
examples/evolution.yml Switches example roles to bundled: references.
evolution_kernel/templates/perf.yml Switches template roles to bundled: references.
evolution_kernel/templates/lint.yml Switches template roles to bundled: references.
evolution_kernel/templates/custom.yml Switches template roles to bundled: references.
evolution_kernel/templates/coverage.yml Switches template roles to bundled: references.
evolution_kernel/templates/benchmark.yml Switches template roles to bundled: references.
evolution_kernel/roles/strategist.py Updates internal comment/docs to match the new planner path reference.
evolution_kernel/roles/goal_evaluator.py Updates internal comment/docs to match the new planner path reference.
evolution_kernel/roles/planner.py Adds the bundled planner role implementation under the package.
evolution_kernel/roles/evaluator.py Adds the bundled evaluator role implementation under the package.
evolution_kernel/roles/executor.sh Adds the bundled executor shell role implementation under the package.
evolution_kernel/config.py Resolves bundled: entries in roles.* during config parsing and wraps errors as ConfigError.
evolution_kernel/_bundled.py Implements bundled: prefix resolution using importlib.resources.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment on lines +32 to +36
resource = files("evolution_kernel").joinpath("roles", name)
with as_file(resource) as path:
resolved = Path(path)
if not resolved.exists():
raise FileNotFoundError(
Comment on lines +3 to 6
The kernel-bundled `evolution_kernel/roles/executor.sh` claude-code path drops permission
flags, so claude refuses to make edits in non-interactive mode. This
wrapper sets `--permission-mode acceptEdits` so the agent actually edits
files. The cost is whatever your Claude Pro / Max subscription already
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants