Repository navigation
docs: highlight efficiency, SnapshotDB structure and agent-native CLI on homepage - #274
Merged
Merged
Conversation
… on homepage Reorder the repository homepage around the four core advantages: import-once query efficiency, replay-enriched SnapshotDB schema, deep forensic analysis, and agent-native JSON contracts. Add a storage/analysis architecture diagram, a comparison table against raw pickles and ad-hoc scripts, a template catalog, and bundled-skill roles in both README.md and README_zh.md.
codeasier
added a commit
that referenced
this pull request
Oct 31, 2026
Compare the unchanged event base fields exactly while independently verifying ordered frame fields through the installed standalone CLI. Require complete source coverage, frame identities, and nonempty evidence; add refusal tests. Merge current main to preserve PR #274 bilingual README updates alongside parser-v3 cache-preservation and latest-request cancellation contracts.
1 task done
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.
📝 Description
Rework the repository homepage so it states what
pt-snapis actually good at, instead of only describing it as "a command-line tool for analyzing PyTorch memory snapshots".Both
README.mdandREADME_zh.mdnow lead with a positioning statement, an architecture diagram, and the same four pillars:callstack/framestorage, read-onlymode=roconnections,--timeout, and explicit dataset work budgets.SnapshotDBis produced by a full allocator replay, not a pickle flattening: post-eventallocated/active/reservedcounters, explicitallocEventId -> freeEventIdblock lifecycles, dynamic vs. preexisting/static separation, deduplicated callstacks, and lossless ordered(filename, line, name)frames.reserved - activegap analysis, peak callstack attribution with coverage, leak-candidate and lifetime forensics, andreport memory-treesingle-file interactive HTML flamegraphs.capabilities/--template-infocontracts with units, denominators, sentinels and interpretation limits;--stack-bytescontext budgeting with retrievable identities; honesthas_more/truncated/total_is_exactflags; strict parameter validation with structured--jsonerror envelopes; and the six bundled diagnostic skills.Structure of the change
pickle -> allocator replay -> SnapshotDB -> templates / reports / skills / Python API).pt-snap?" comparison table against raw pickles, ad-hoc scripts and static HTML dumps.--jsoncoverage list, dataset limits, and the agent/collection notes.🔗 Related Issue
N/A
🧪 Testing
Verified render and contract, without running import/install/publication:
pytest tests/test_docs_onboarding.py tests/test_governance.py # 56 passed git diff --checkCovered gates:
README.md/README_zh.mdresolve.AGENTS.md#development-and-checksandbasedpyrightpointers retained.✅ Checklist
No snapshot runtime, query, schema or CLI behavior changed; this is presentation plus an accurate catalog of already-shipped capabilities.
📸 Screenshots
GitHub Markdown rendering of the new homepage (Mermaid + tables). No CLI output changed.
📋 Additional Notes
Chinese text mirrors the English structure and keeps every executable identifier (flags, template names, JSON keys, table/column names) exact.