py-harness-cli 0.3.0__py3-none-any.whl

finetune/__init__.py

@@ -0,0 +1 @@
+"""Build LoRA datasets and train the python-vibe model."""

finetune/agent_system.py

@@ -0,0 +1,41 @@
+"""System prompt for the everyday tool loop. Kept short for the 8B.
+
+The paths here are placeholders, not examples. An 8B copies the first block
+it sees, so a literal path in this template is a path it will write to in
+whatever repo it is pointed at. `harness.agent.prompt` fills them from the
+project in front of the model before the prompt is sent.
+
+Placeholders: {{module}} {{test}}
+"""
+
+AGENT_SYSTEM = """\
+One Action per turn. Never paste a list of Actions. Copy one block only.
+
+Action: locate
+Query: apply_source
+
+Action: patch
+Path: {{module}}
+Append:
+def multiply(left: int, right: int) -> int:
+    return left * right
+
+Action: run
+Argv: -m unittest discover -s tests -q
+
+Action: ask
+Query: one short question, when the task could mean two different things
+Append:
+- the first reading
+- the second reading
+
+Action: done
+Summary: one sentence, in your own words, about this project
+
+If the harness already shows # auto-read, Action: done.
+If the harness already shows (no hits) for a new function, Action: patch + Append.
+Find: must be a full unique line. Path stays in the project. No curl|sh.
+Names are snake_case (total_price), not calc/tmp/x.
+Never answer by repeating an instruction you were given. Quote the code.
+Ship an issue: issue → branch → patch → commit → push → pr. No force. Not main.
+"""

finetune/agent_traces.py

@@ -0,0 +1,157 @@
+"""Seed explore→edit→run traces. Templates, not 2k live sessions."""
+
+from __future__ import annotations
+
+from finetune.agent_system import AGENT_SYSTEM
+
+
+def seed_pairs() -> list[tuple[str, str]]:
+    pairs: list[tuple[str, str]] = []
+    files = (
+        "src/app.py",
+        "tools/system/work_items/validation.py",
+        "lib/stats.py",
+        "pkg/util_stats.py",
+    )
+    for path in files:
+        pairs.append(
+            (
+                f"Project root: /tmp/app\nTask: find where {path.split('/')[-1]} defines main helpers\n"
+                "Start with Action: grep or Action: read. Do not Action: done yet.",
+                f"Action: grep\nQuery: def ",
+            )
+        )
+        pairs.append(
+            (
+                f"Tool result:\n{path}:12:def compute_total(rows):\n\nNext Action:",
+                f"Action: read\nPath: {path}",
+            )
+        )
+        pairs.append(
+            (
+                f"Tool result:\n{path} (1200 chars)\ndef compute_total(rows):\n    return tota\n\nNext Action:",
+                f"Action: edit\nPath: {path}\n```python\ndef compute_total(rows):\n    return sum(rows)\n```",
+            )
+        )
+        pairs.append(
+            (
+                "Tool result:\nwrote "
+                + path
+                + " (backup "
+                + path.split("/")[-1]
+                + ".bak)\n\nNext Action:",
+                "Action: run\nArgv: -m unittest discover -s tests -q",
+            )
+        )
+        pairs.append(
+            (
+                "Tool result:\nexit 0\n.\n----------------------------------------------------------------------\nRan 1 test in 0.01s\n\nOK\n\nNext Action:",
+                "Action: done\nSummary: Fixed NameError in compute_total (tota → sum(rows)) and tests passed.",
+            )
+        )
+
+    pairs.append(
+        (
+            "Could not parse. Reply with one Action: glob|grep|read|edit|run|done",
+            "Action: grep\nQuery: NameError",
+        )
+    )
+    pairs.append(("Tool result:\n(no hits)\n\nNext Action:", "Action: glob\nPattern: **/*.py"))
+    pairs.append(
+        (
+            "Tool result:\npkg/util_stats.py\ntests/test_util_stats.py\n\nNext Action:",
+            "Action: read\nPath: tests/test_util_stats.py",
+        )
+    )
+    pairs.append(
+        (
+            "Project root: /tmp/app\nTask: do not rewrite the whole repo after seeing __init__.py\n"
+            "Start with Action: grep or Action: read. Do not Action: done yet.",
+            "Action: grep\nQuery: TODO|FIXME|NameError",
+        )
+    )
+    for query in ("class ", "import json", "def test_", "except Exception", "Path("):
+        pairs.append((f"Find uses of {query.strip()}", f"Action: grep\nQuery: {query.strip()}"))
+    pairs.append(
+        (
+            "Tool result:\nsrc/app.py:1:from pathlib import Path\n\nNext Action:",
+            "Action: read\nPath: src/app.py",
+        )
+    )
+    pairs.append(
+        (
+            "Task: run the unit tests after the edit. Do not Action: done yet.",
+            "Action: run\nArgv: -m unittest discover -s tests -q",
+        )
+    )
+    pairs.append(
+        (
+            "Tool result:\nexit 1\nNameError: name 'tota' is not defined\n\nNext Action:",
+            "Action: grep\nQuery: tota",
+        )
+    )
+    pairs.append(
+        (
+            "Tool result:\npkg/util_stats.py:71:return tota\n\nNext Action:",
+            "Action: patch\nPath: pkg/util_stats.py\nFind: return tota\nReplace: return sum(cleaned)",
+        )
+    )
+    pairs.append(
+        (
+            "Mode: large  files=120  size=400.0 KB\n"
+            "Large project — use the harness.\n"
+            "Start with Action: map, then grep. Do not Action: done yet.",
+            "Action: map\nScope: src",
+        )
+    )
+    pairs.append(
+        (
+            "Tool result:\nmap src  12 files  40.0 KB\n  src/harness/code.py  3.1 KB\n\nNext Action:",
+            "Action: grep\nQuery: def apply_source",
+        )
+    )
+    pairs.append(
+        (
+            "This is a question. Read what you need, then Action: done with the answer. "
+            "Do not edit unless asked.",
+            "Action: read\nPath: src/harness/code.py",
+        )
+    )
+    pairs.append(
+        (
+            "This is an add-feature task. Grep first. If it is missing, add the "
+            "smallest change plus a test, then run. Do not invent extras.",
+            "Action: skill\nName: add-feature",
+        )
+    )
+    pairs.append(
+        (
+            "This is a new-package task. First Action: edit Path: pkg/__init__.py "
+            "(exports only).",
+            "Action: edit\nPath: pkg/__init__.py\n```python\n"
+            '"""Public exports only. Implementation lives in sibling modules."""\n```',
+        )
+    )
+    pairs.append(
+        (
+            "This is a smell/rename task. Patch one opaque name to readable "
+            "snake_case. Do not add features.",
+            "Action: patch\nPath: pkg/mathy.py\nFind: def calc(x, y):\n"
+            "Replace: def total_price(quantity: int, unit_price: int) -> int:",
+        )
+    )
+    pairs.append(
+        (
+            "Task: add a function multiply(a, b) and a unit test\n",
+            "Action: grep\nQuery: def multiply",
+        )
+    )
+    return pairs
+
+
+def all_pairs() -> list[tuple[str, str]]:
+    return seed_pairs()
+
+
+def system_prompt() -> str:
+    return AGENT_SYSTEM

finetune/everyday.py

@@ -0,0 +1,30 @@
+"""Everyday laptop brain vs the public 0.5B sidecar."""
+
+from __future__ import annotations
+
+import os
+
+# 0.5B stays on the Hub and in smoke. This is what agent.py should use daily.
+DEFAULT_EVERYDAY_OLLAMA = os.environ.get("OLLAMA_MODEL", "llama3.1:8b")
+TINY_OLLAMA = "qwen2.5-coder:0.5b"
+EVERYDAY_OLLAMA_CHOICES = (
+    "llama3.1:8b",
+    "qwen2.5-coder:7b",
+    "qwen2.5-coder:14b",
+    "qwen2.5-coder:32b",
+)
+EVERYDAY_MLX_BASE = "mlx-community/Qwen2.5-Coder-7B-Instruct-4bit"
+EVERYDAY_SLUG = "python-vibe-8b"
+TINY_MODELS = frozenset(
+    {
+        TINY_OLLAMA,
+        "qwen2.5-coder:0.5b",
+        "python-vibe",
+        "python-vibe-0.5b",
+    }
+)
+
+
+def is_tiny_model(name: str) -> bool:
+    lowered = name.strip().lower()
+    return lowered in TINY_MODELS or lowered.endswith(":0.5b") or lowered.endswith("-0.5b")

finetune/hf_ollama.py

@@ -0,0 +1,158 @@
+"""Hugging Face GGUFs that are not in the Ollama library.
+
+OpenCoder 8B and SWE-agent-LM 7B fit this laptop as Q4_K_M (~4.7 GB
+each). They are not `ollama pull` tags. Download the GGUF, write a
+Modelfile that only names the file, then `ollama create`. The harness
+already sends the agent system prompt; do not bake it into the tag.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import tempfile
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+Downloader = Callable[[str, str], Path]
+Creator = Callable[[str, Path], None]
+
+
+@dataclass(frozen=True)
+class ImportSpec:
+    key: str
+    ollama_tag: str
+    source: str
+    gguf_repo: str
+    filename: str
+    default_quant: str
+    about_gb: float
+    license: str
+    note: str
+
+
+IMPORTS: dict[str, ImportSpec] = {
+    "opencoder": ImportSpec(
+        key="opencoder",
+        ollama_tag="opencoder:8b",
+        source="infly/OpenCoder-8B-Instruct",
+        gguf_repo="bartowski/OpenCoder-8B-Instruct-GGUF",
+        filename="OpenCoder-8B-Instruct-{quant}.gguf",
+        default_quant="Q4_K_M",
+        about_gb=4.7,
+        license="INF",
+        note="Code instruct. Not trained on python-vibe Action:.",
+    ),
+    "swe-agent-lm": ImportSpec(
+        key="swe-agent-lm",
+        ollama_tag="swe-agent-lm:7b",
+        source="SWE-bench/SWE-agent-LM-7B",
+        gguf_repo="mradermacher/SWE-agent-LM-7B-GGUF",
+        filename="SWE-agent-LM-7B.{quant}.gguf",
+        default_quant="Q4_K_M",
+        about_gb=4.7,
+        license="Apache-2.0",
+        note="Qwen2.5-Coder-7B-Instruct plus 5k SWE-agent traces. Their tools, not Action:.",
+    ),
+}
+
+LAPTOP_QUANT = "Q4_K_M"
+
+
+def resolve(name: str) -> ImportSpec:
+    try:
+        return IMPORTS[name]
+    except KeyError:
+        known = ", ".join(sorted(IMPORTS))
+        raise SystemExit(f"unknown import {name!r}: use {known}") from None
+
+
+def names() -> list[str]:
+    return sorted(IMPORTS)
+
+
+def gguf_filename(spec: ImportSpec, quant: str | None = None) -> str:
+    chosen = (quant or spec.default_quant).strip()
+    if not chosen:
+        raise SystemExit("quant is empty")
+    return spec.filename.format(quant=chosen)
+
+
+def write_modelfile(gguf: Path, dest: Path) -> Path:
+    if not gguf.is_file():
+        raise SystemExit(f"no GGUF: {gguf}")
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text(f"FROM {gguf.resolve()}\n", encoding="utf-8")
+    return dest
+
+
+def _hf_download(repo_id: str, filename: str) -> Path:
+    from huggingface_hub import hf_hub_download
+
+    from finetune.huggingface_store import optional_token
+
+    return Path(
+        hf_hub_download(
+            repo_id=repo_id,
+            filename=filename,
+            token=optional_token(),
+        )
+    )
+
+
+def download_gguf(
+    spec: ImportSpec,
+    *,
+    quant: str | None = None,
+    downloader: Downloader | None = None,
+) -> Path:
+    filename = gguf_filename(spec, quant)
+    print(f"downloading https://huggingface.co/{spec.gguf_repo}/{filename}")
+    fetch = downloader or _hf_download
+    return fetch(spec.gguf_repo, filename)
+
+
+def _ollama_create(tag: str, gguf: Path) -> None:
+    ollama = shutil.which("ollama")
+    if not ollama:
+        raise SystemExit("ollama not on PATH")
+    with tempfile.TemporaryDirectory() as tmp:
+        dest = write_modelfile(gguf, Path(tmp) / "Modelfile")
+        subprocess.check_call([ollama, "create", tag, "-f", str(dest)])
+
+
+def import_one(
+    name: str,
+    *,
+    quant: str | None = None,
+    create: bool = True,
+    downloader: Downloader | None = None,
+    creator: Creator | None = None,
+) -> tuple[ImportSpec, Path]:
+    spec = resolve(name)
+    gguf = download_gguf(spec, quant=quant, downloader=downloader)
+    if create:
+        make = creator or _ollama_create
+        make(spec.ollama_tag, gguf)
+    return spec, gguf
+
+
+def import_many(
+    keys: Sequence[str],
+    *,
+    quant: str | None = None,
+    create: bool = True,
+    downloader: Downloader | None = None,
+    creator: Creator | None = None,
+) -> list[tuple[ImportSpec, Path]]:
+    return [
+        import_one(
+            key,
+            quant=quant,
+            create=create,
+            downloader=downloader,
+            creator=creator,
+        )
+        for key in keys
+    ]

finetune/huggingface_store.py

@@ -0,0 +1,144 @@
+"""Download official Hub weights; upload only to HF_USER / HF_REPO / whoami."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+from pathlib import Path
+
+from finetune.models import ModelSpec, publish_hf_repo
+from finetune.paths import PROJECT_ROOT
+
+CARDS = PROJECT_ROOT / "cards"
+BEST_ADAPTER = "0000100_adapters.safetensors"
+_HUB_CONFIG_KEYS = ("fine_tune_type", "num_layers", "lora_parameters")
+
+
+def require_token() -> str:
+    token = os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN")
+    if token:
+        return token
+    try:
+        from huggingface_hub import get_token
+
+        token = get_token()
+    except Exception:
+        token = None
+    if not token:
+        raise SystemExit(
+            "No Hugging Face token. Run `hf auth login` or export HF_TOKEN. "
+            "Uploads go to HF_REPO, or HF_USER/<slug>, or your logged-in account — "
+            "never to the official repo unless that is you."
+        )
+    return token
+
+
+def write_card(spec: ModelSpec, dest: Path) -> Path:
+    src = CARDS / f"{spec.name}.md"
+    if not src.is_file():
+        raise FileNotFoundError(src)
+    dest.mkdir(parents=True, exist_ok=True)
+    readme = dest / "README.md"
+    readme.write_text(src.read_text(encoding="utf-8"), encoding="utf-8")
+    return readme
+
+
+def push_card(spec: ModelSpec, *, token: str) -> str:
+    """Upload only the model card, leaving the weights untouched.
+
+    The description changes far more often than the weights do, and
+    re-uploading a folder to change one text file is both slow and a way to
+    publish something by accident.
+    """
+    import tempfile
+
+    from huggingface_hub import HfApi
+
+    repo_id = publish_hf_repo(spec)
+    with tempfile.TemporaryDirectory() as tmp:
+        readme = write_card(spec, Path(tmp))
+        HfApi(token=token).upload_file(
+            path_or_fileobj=str(readme),
+            path_in_repo="README.md",
+            repo_id=repo_id,
+            repo_type="model",
+            commit_message=f"update the {spec.name} card",
+        )
+    return f"https://huggingface.co/{repo_id}"
+
+
+def push_folder(spec: ModelSpec, folder: Path, *, private: bool, token: str) -> str:
+    if not folder.is_dir() or not any(folder.iterdir()):
+        raise FileNotFoundError(f"nothing to upload in {folder}")
+    from huggingface_hub import HfApi
+
+    repo_id = publish_hf_repo(spec)
+    write_card(spec, folder)
+    api = HfApi(token=token)
+    api.create_repo(repo_id, repo_type="model", private=private, exist_ok=True)
+    api.upload_folder(
+        folder_path=str(folder),
+        repo_id=repo_id,
+        repo_type="model",
+        commit_message=f"save {spec.name} ({folder.name})",
+    )
+    return f"https://huggingface.co/{repo_id}"
+
+
+def optional_token() -> str | None:
+    try:
+        return require_token()
+    except SystemExit:
+        return None
+
+
+def _weights_file(adapter_dir: Path) -> Path | None:
+    best = adapter_dir / BEST_ADAPTER
+    latest = adapter_dir / "adapters.safetensors"
+    if best.is_file():
+        return best
+    if latest.is_file():
+        return latest
+    return None
+
+
+def stage_adapter_bundle(spec: ModelSpec) -> Path:
+    """Copy the best checkpoint + a path-free config into a folder safe to upload."""
+    src = spec.adapter_path
+    weights = _weights_file(src)
+    if weights is None:
+        raise FileNotFoundError(f"no adapters in {src}")
+    dest = spec.adapter_path.parent / f"{spec.name}-hub"
+    if dest.exists():
+        shutil.rmtree(dest)
+    dest.mkdir(parents=True)
+    shutil.copy2(weights, dest / "adapters.safetensors")
+    cfg_path = src / "adapter_config.json"
+    raw = json.loads(cfg_path.read_text(encoding="utf-8")) if cfg_path.is_file() else {}
+    slim = {key: raw[key] for key in _HUB_CONFIG_KEYS if key in raw}
+    (dest / "adapter_config.json").write_text(
+        json.dumps(slim, indent=2) + "\n", encoding="utf-8"
+    )
+    write_card(spec, dest)
+    return dest
+
+
+def pull_folder(spec: ModelSpec, dest: Path, *, token: str | None) -> Path:
+    from huggingface_hub import snapshot_download
+
+    dest.mkdir(parents=True, exist_ok=True)
+    snapshot_download(
+        repo_id=spec.hf_repo,
+        local_dir=str(dest),
+        token=token,
+    )
+    return dest
+
+
+def ensure_adapters(spec: ModelSpec) -> Path:
+    """Local adapters if present; otherwise download the public Hub repo."""
+    if _weights_file(spec.adapter_path) is not None:
+        return spec.adapter_path
+    print(f"downloading https://huggingface.co/{spec.hf_repo} → {spec.adapter_path}")
+    return pull_folder(spec, spec.adapter_path, token=optional_token())

finetune/models.py

@@ -0,0 +1,74 @@
+"""Qwen2.5-Coder-0.5B 4-bit — fits a cheap cloud box (~400 MB)."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from finetune.paths import ADAPTERS_ROOT, FUSED_ROOT
+from finetune.systems import PYTHON_VIBE_SYSTEM
+
+# Published weights anyone may download. Not a contributor identity.
+# Uploads never use this unless HF_REPO / HF_USER / `hf auth login` say so.
+OFFICIAL_HF_REPO = "YauhenBichel/python-vibe-0.5b"
+
+
+@dataclass(frozen=True)
+class ModelSpec:
+    name: str
+    mlx_base: str
+    ollama_base: str
+    hf_repo: str
+    system: str
+    adapter_path: Path
+    fused_path: Path
+    ram_mb: int
+
+    @property
+    def hf_slug(self) -> str:
+        return self.hf_repo.rsplit("/", 1)[-1]
+
+
+def logged_in_hf_user() -> str | None:
+    try:
+        from huggingface_hub import whoami
+
+        info = whoami()
+    except Exception:
+        return None
+    if isinstance(info, dict):
+        name = info.get("name")
+        if isinstance(name, str) and name:
+            return name
+    return None
+
+
+def publish_hf_repo(spec: ModelSpec) -> str:
+    """Where *this machine* may upload. Never defaults to the official account."""
+    override = (os.environ.get("HF_REPO") or os.environ.get("PYTHON_VIBE_HF_REPO") or "").strip()
+    if override:
+        return override
+    user = (os.environ.get("HF_USER") or "").strip() or logged_in_hf_user()
+    if not user:
+        raise SystemExit(
+            "Refusing to upload to the official Hub repo. Set HF_USER or HF_REPO "
+            f"to your namespace (example: HF_USER=alice → alice/{spec.hf_slug}), "
+            "or run `hf auth login` as yourself. "
+            f"People download official weights from {spec.hf_repo}."
+        )
+    return f"{user}/{spec.hf_slug}"
+
+
+SPECS: dict[str, ModelSpec] = {
+    "python-vibe": ModelSpec(
+        name="python-vibe",
+        mlx_base="mlx-community/Qwen2.5-Coder-0.5B-Instruct-4bit",
+        ollama_base="qwen2.5-coder:0.5b",
+        hf_repo=OFFICIAL_HF_REPO,
+        system=PYTHON_VIBE_SYSTEM,
+        adapter_path=ADAPTERS_ROOT / "python-vibe",
+        fused_path=FUSED_ROOT / "python-vibe",
+        ram_mb=400,
+    ),
+}

finetune/paths.py

@@ -0,0 +1,11 @@
+"""Default locations for this project's outputs."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+DATA_ROOT = PROJECT_ROOT / "data"
+ADAPTERS_ROOT = PROJECT_ROOT / "adapters"
+FUSED_ROOT = PROJECT_ROOT / "fused"
+CONFIGS_ROOT = PROJECT_ROOT / "configs"