Repository navigation
feat(skills): Add a setup-and-run workflow for first-time users - #12
Merged
Merged
Conversation
lyfne123
force-pushed
the
feat/setup-and-run-skill
branch
from
August 19, 2026 03:54
d4277a4 to
36a4a13
Compare
A new user arriving at a PyPTO consumer repository has no single path from a fresh checkout to a validated model run. The setup guide, the platform guide, the first-kernel walkthrough, and the model pages each own one fragment, and none of them states which case to run first, what a passing stage looks like, or when it is safe to move on. The usual result is that someone starts at a multi-layer forward, hits an error produced three stages earlier, and reads it as a model fault. Add `setup-and-run` to the user plugin. It owns the sequence and the gates: a target stage that fixes simulator versus device and card count before anything runs; an environment stage whose gate is that the framework imports, the assembler answers `--version`, and the tile-ISA checkout matches its pin; a smoke stage on the repository's smallest end-to-end example; and a model stage that climbs from an operator to one layer to a multi-layer forward instead of starting at the top. No stage advances on a partial pass, so a failure is attributed to the stage that caused it rather than to the case that surfaced it. The consumer repository keeps its own setup, platform, and model documentation. The skill locates those guides rather than restating their commands, treats their pins as the version source of truth, and carries a pypto-lib ladder only as a worked example that must be re-checked against `--help` before it is run. A first-run failure table maps the symptoms a new user actually hits — an assembler binary that satisfies an existence check and still fails every real compile, compile-side and runtime-side tile-ISA checkouts that have drifted, a runtime installed before the vendor environment was sourced — to the stage that owns each one.
Walking the skill on a fresh checkout against a real toolchain showed the environment gate passing on an installation that then broke three of four model rungs. The assembler answered `--version`, so the gate cleared, but it was two releases away from the version the framework checkout pins. Kernels using the affected tile ops failed to compile with contract errors that read as kernel bugs, while kernels avoiding those ops compiled and validated normally; pointing the same rung at the pinned assembler made it pass. The tile-ISA line had the opposite fault: it compared a checkout the build was not using and would have blocked a working environment. Make the gate a comparison. Liveness checks stay, but the gate is now the installed assembler version against the checkout's `versions.env` pin and the installed tile-ISA HEAD against `pto_isa.pin`, with the note that a machine usually holds several tile-ISA copies and every one must be reconciled. Route tile-op contract errors — an op requiring an explicit temporary, a skipped memory-planning pass — back to that comparison instead of letting Stage 3 attribute them to a model. Separate the two things exit 0 can mean. A simulator platform can select a compile-only path that lowers the program and prints no run or validation stages, so the smoke and ladder gates now read the stages rather than the exit code, and a rung that only lowers no longer licenses the next one. Mark the quantized layer rung as compile-only on a simulator, and widen the runtime failure row, which was written as device-only and also fires on simulators.
Running the ladder on a real accelerator, rather than a simulator, moved two failure modes into the wrong section of the skill. A skewed assembler does not only break compiles. The single-layer decode forward compiled cleanly under an assembler two releases past the pin, ran for seventy-four seconds, and died with a generic on-device exception that reads as a scheduler or runtime fault; the identical case passed in nineteen seconds once the pin was honored. The runtime-failure row sent that straight to the debugging guide, which is where an hour disappears. Send it back to the Stage 1 pin comparison first, and only past this runbook once the pins agree. Not every rung reports through the harness. The multi-layer forward validates against a host reference and prints its own summary — match counts, an error percentage, a maximum absolute error — and never prints the harness passing line. Stage 4 now says to find and quote the line the rung actually emitted instead of asserting a result its output does not contain. Also scope the ladder to what it buys. It exists to localize failures, so it earns its cost on a freshly built or just-reconciled environment and wastes the user's time on a proven one, where the right move is to start at the rung they asked for and fall back only on failure.
lyfne123
force-pushed
the
feat/setup-and-run-skill
branch
from
August 19, 2026 06:44
91ff932 to
dbc4b38
Compare
setup-and-run carried a table of one repository's model entry points, their flags, and their platform support. Those are properties of that tree, not of this workflow: they change when it changes, and a copy living here goes stale without anything in that repository's review being able to notice. Writing the table already required correcting it twice in a single sitting, once for a documentation reorganization and once for an entry point whose simulator run turned out to lower without validating. Replace the table with a lookup. The skill now finds the repository skill that owns the inventory and lets it choose the rung, and when a repository publishes none, derives rungs from that repository's own documentation and CLI while reporting the gap rather than filling it from memory. The two properties that genuinely generalize survive as checks: one entry point often serving several goals behind a flag, and a tree with no simulator form having no cheap rung to fall back to. The smoke stage is now a lookup for the same reason, since naming an example path from memory is the same failure at smaller scale.
Hzfengsy
approved these changes
Aug 19, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A new user arriving at a PyPTO consumer repository has no single path from a
fresh checkout to a validated model run. The setup guide, the platform guide,
the first-kernel walkthrough, and the model pages each own one fragment, and
none of them states which case to run first, what a passing stage looks like,
or when it is safe to move on. The usual result is that someone starts at a
multi-layer forward, hits an error produced three stages earlier, and reads it
as a model fault.
Add
setup-and-runto the user plugin. It owns the sequence and the gates: atarget stage that fixes simulator versus device and card count before anything
runs; an environment stage whose gate is that the framework imports, the
assembler answers
--version, and the tile-ISA checkout matches its pin; asmoke stage on the repository's smallest end-to-end example; and a model stage
that climbs from an operator to one layer to a multi-layer forward instead of
starting at the top. No stage advances on a partial pass, so a failure is
attributed to the stage that caused it rather than to the case that surfaced
it.
The consumer repository keeps its own setup, platform, and model
documentation. The skill locates those guides rather than restating their
commands, treats their pins as the version source of truth, and carries a
pypto-lib ladder only as a worked example that must be re-checked against
--helpbefore it is run. A first-run failure table maps the symptoms a newuser actually hits — an assembler binary that satisfies an existence check and
still fails every real compile, compile-side and runtime-side tile-ISA
checkouts that have drifted, a runtime installed before the vendor environment
was sourced — to the stage that owns each one.