Skip to content

feat(skills): Add a setup-and-run workflow for first-time users - #12

Merged
Hzfengsy merged 4 commits into
mainfrom
feat/setup-and-run-skill
Aug 19, 2026
Merged

Hzfengsy merged 4 commits into
mainfrom
feat/setup-and-run-skill

Conversation

@lyfne123

Copy link
Copy Markdown
Collaborator

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.

@lyfne123
lyfne123 force-pushed the feat/setup-and-run-skill branch from d4277a4 to 36a4a13 Compare August 19, 2026 03:54
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
lyfne123 force-pushed the feat/setup-and-run-skill branch from 91ff932 to dbc4b38 Compare August 19, 2026 06:44
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
Hzfengsy merged commit 25500e6 into main Aug 19, 2026
2 checks passed
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