File size: 10,094 Bytes

"""Create a portable Colab walkthrough using the standard notebook JSON format."""
import ast
from contextlib import redirect_stdout
import io
import json
from pathlib import Path


def build():
    cells = []
    def markdown(text):
        cells.append({"cell_type": "markdown", "id": f"cell-{len(cells):02}", "metadata": {}, "source": text})
    def code(text):
        cells.append({"cell_type": "code", "id": f"cell-{len(cells):02}", "metadata": {},
                      "source": text, "execution_count": None, "outputs": []})
    markdown("""# PocketVision: cloud training for chat, code and writing

## Goal
Run a small QLoRA smoke experiment on a **Colab cloud GPU**, then inspect a candidate before scaling up.
The PC only displays this notebook. No trained 4B weights are included.

**Validation status:** the saved outputs show a local dry run only. Cloud installation, source authentication,
GPU memory, training, and model quality remain untested. Free Colab GPU availability is not guaranteed.
Choose a free runtime yourself; this notebook does not purchase compute or alter subscriptions.

English Wikipedia restricts AI-generated article prose. Use the reference-article task for other contexts,
and the outline/source-review task for Wikipedia preparation.
[Current guideline](https://en.wikipedia.org/wiki/Wikipedia:Writing_articles_with_large_language_models).
""")
    markdown("""## Setup
1. Upload this notebook to Colab and select a GPU runtime.
2. Set `DRY_RUN = False` below. Set `RUN_TRAINING = True` only when ready to use the allocated GPU.
3. Store an existing Hugging Face **read token** in Colab Secrets as `HF_TOKEN` and grant this notebook access.
   The source repository is private. Do not paste a token into a code cell or chat.
4. The Drive step asks you to mount Google Drive. This grants notebook code access to the mounted files;
   only the named PocketVision folder is used here for checkpoints.
""")
    code('''from pathlib import Path
import json
import os
import subprocess
import sys

DRY_RUN = True
RUN_TRAINING = False
SOURCE_REPO = "gamedevelop/pocketvision-chat-code"
SOURCE_REVISION = None  # None resolves and records one immutable commit before downloading.
PILOT_ROWS = 200        # Dependency/memory smoke test. Use 20000 only after reviewing the smoke run.
HOLDOUT_PER_SOURCE = 2
MAX_STEPS = 25
RUN_NAME = "writing-smoke-01"  # Change for a fresh run; existing output is never overwritten.
RESUME_CHECKPOINT = None       # Or an existing checkpoint-N directory from the same run.
cloud_python = Path("/content/pocketvision-venv/bin/python")
source_dir = None
run_dir = None
print("Dry-run validation only; no cloud operations." if DRY_RUN else "Cloud setup enabled; training still needs RUN_TRAINING=True.")
''')
    markdown("""### 1. Install an isolated cloud environment
Installation uses a separate environment, preserving the notebook kernel's packages.
The next check requires a CUDA GPU before any model weights are loaded.
""")
    code('''if not DRY_RUN:
    subprocess.run([sys.executable, "-m", "venv", str(cloud_python.parent.parent)], check=True)
    subprocess.run([str(cloud_python), "-m", "pip", "install", "torch==2.9.1",
                    "--index-url", "https://download.pytorch.org/whl/cu128"], check=True)
    subprocess.run([sys.executable, "-m", "pip", "install", "huggingface-hub==0.36.2"], check=True)
    subprocess.run([str(cloud_python), "-c",
                    "import torch; assert torch.cuda.is_available(), 'Select a Colab GPU runtime'; print(torch.cuda.get_device_name(0))"], check=True)
else:
    print("Skipped: dependency installation and GPU allocation checks.")
''')
    markdown("""### 2. Download only the versioned source
The commit is resolved once and logged; pretrained weights and source ZIPs are excluded.
The model and datasets have their own pinned revisions in the configuration.
""")
    code('''if not DRY_RUN:
    from google.colab import userdata
    from huggingface_hub import HfApi, snapshot_download
    os.environ["HF_TOKEN"] = userdata.get("HF_TOKEN")
    revision = HfApi().model_info(SOURCE_REPO, revision=SOURCE_REVISION or "main").sha
    source_dir = Path(snapshot_download(SOURCE_REPO, revision=revision, allow_patterns=[
        "app.py", "chat.py", "LICENSE*", "chatcode/*.py", "chatcode/*.json", "chatcode/*.txt", "chatcode/*.md"]))
    assert (source_dir / "chatcode/articles.py").is_file(), "This source commit predates article support."
    subprocess.run([str(cloud_python), "-m", "pip", "install", "-r",
                    str(source_dir / "chatcode/requirements-cloud.txt")], check=True)
    subprocess.run([str(cloud_python), "-m", "pip", "check"], check=True)
    print("Source commit:", revision)
else:
    print("Skipped: private Hub download and authentication. No token requested.")
''')
    markdown("""### 3. Use persistent storage
Colab's runtime disk is temporary. Drive contains the data manifest, optimizer checkpoints and candidate.
Only this new run folder is created; no existing files are deleted.
""")
    code('''if not DRY_RUN:
    from google.colab import drive
    drive.mount("/content/drive")
    checkpoint_root = Path("/content/drive/MyDrive/PocketVision-writing")
    run_dir = checkpoint_root / RUN_NAME
    if run_dir.exists() and any(run_dir.iterdir()) and not RESUME_CHECKPOINT:
        raise FileExistsError("Choose a fresh RUN_NAME or explicitly resume an existing checkpoint.")
    run_dir.mkdir(parents=True, exist_ok=True)
    (run_dir / "run-info.json").write_text(json.dumps({"source_repo": SOURCE_REPO,
        "source_revision": revision, "pilot_rows": PILOT_ROWS, "max_steps": MAX_STEPS}, indent=2))
    print("Persistent run directory:", run_dir)
else:
    print("Skipped: Drive authorization and persistent cloud writes.")
''')
    markdown("""## Steps
### 4. Prepare data and run the capped experiment
This cell streams selected chat, coding, rewriting and summarization data, adds the small authored behavior
packets, and runs 25 optimizer steps. It may consume significant GPU time even on a small sample.
The full 20,000-example experiment is a separate decision after measuring steps/second and memory.
""")
    code('''if not DRY_RUN and RUN_TRAINING:
    data_dir = run_dir / "data"
    if not (data_dir / "manifest.json").is_file():
        subprocess.run([str(cloud_python), "-m", "chatcode.data", "--output", str(data_dir),
                        "--train", str(PILOT_ROWS), "--holdout-per-source", str(HOLDOUT_PER_SOURCE)], cwd=source_dir, check=True)
    command = [str(cloud_python), "-m", "chatcode.train", "--data", str(data_dir),
               "--output", str(run_dir / "training"), "--max-steps", str(MAX_STEPS)]
    if RESUME_CHECKPOINT:
        command.extend(["--resume-from-checkpoint", str(RESUME_CHECKPOINT)])
    subprocess.run(command, cwd=source_dir, check=True)
else:
    print("Skipped: dataset preparation and weight training. No model weights downloaded.")
''')
    markdown("""## Checks
### 5. Compare base and candidate
The automated article check measures JSON/citation-ID validity on four held-out fictional cases.
It does **not** measure factual accuracy, source reliability, or Wikipedia suitability. Inspect all saved
outputs, and separately test chat and code regressions. Do not execute generated programs outside a sandbox.
""")
    code('''if not DRY_RUN and RUN_TRAINING:
    candidate_dir = run_dir / "training/adapter"
    subprocess.run([str(cloud_python), "-m", "chatcode.evaluate_articles", "--adapter", str(candidate_dir),
                    "--output", str(run_dir / "article-evaluation.json")], cwd=source_dir, check=True)
    print("Candidate and evaluation saved under:", run_dir)
else:
    print("Skipped: model evaluation. No accuracy or quality result is claimed.")
''')
    markdown("""## Next Steps
Review the cloud smoke run before raising `PILOT_ROWS`, holdout sizes or run duration. Training data changes
require a new run directory; do not resume a checkpoint against different data.
The source recipe alone does not improve weights. Compare factual support and neutrality with the base,
and check programming and conversation regressions before publishing a candidate.
No upload or Wikipedia publication is performed by this notebook. A later Hub upload needs a separate
write-scoped credential and a reviewed candidate. Do not share notebook outputs containing credentials.
""")
    notebook = {"nbformat": 4, "nbformat_minor": 5,
                "metadata": {"kernelspec": {"display_name": "Python 3", "language": "python", "name": "python3"},
                             "language_info": {"name": "python", "version": "3.12"},
                             "pocketvision_validation": "local_dry_run_only_no_cloud_execution"}, "cells": cells}
    return notebook


def validate_and_dry_run(notebook):
    """Structural and Python syntax checks when nbformat is unavailable locally."""
    assert notebook["nbformat"] == 4 and notebook["nbformat_minor"] == 5
    namespace, ids, count = {}, set(), 0
    for cell in notebook["cells"]:
        assert cell["id"] not in ids and isinstance(cell["metadata"], dict) and isinstance(cell["source"], str)
        ids.add(cell["id"])
        assert cell["cell_type"] in {"markdown", "code"}
        if cell["cell_type"] == "code":
            compiled = compile(ast.parse(cell["source"]), "<notebook-cell>", "exec")
            output = io.StringIO()
            with redirect_stdout(output):
                exec(compiled, namespace)
            count += 1
            cell["execution_count"] = count
            cell["outputs"] = [{"output_type": "stream", "name": "stdout", "text": output.getvalue()}]
    assert namespace["DRY_RUN"] is True and namespace["RUN_TRAINING"] is False
    return notebook


if __name__ == "__main__":
    path = Path(__file__).with_name("cloud_training.ipynb")
    path.write_text(json.dumps(validate_and_dry_run(build()), ensure_ascii=False, indent=2), encoding="utf-8")
    print(f"Wrote {path}; all cells executed only in dry-run mode. GPU execution remains unverified.")