Skip to content

docs: highlight efficiency, SnapshotDB structure and agent-native CLI on homepage - #274

Merged
codeasier merged 1 commit into
mainfrom
docs/homepage-value-proposition
Oct 31, 2026
Merged

codeasier merged 1 commit into
mainfrom
docs/homepage-value-proposition

Conversation

@codeasier

Copy link
Copy Markdown
Owner

📝 Description

Rework the repository homepage so it states what pt-snap is actually good at, instead of only describing it as "a command-line tool for analyzing PyTorch memory snapshots".

Both README.md and README_zh.md now lead with a positioning statement, an architecture diagram, and the same four pillars:

  1. Efficiency — import once and query in milliseconds: SHA-256 import cache reuse, offline analysis with no PyTorch/accelerator, deduplicated callstack/frame storage, read-only mode=ro connections, --timeout, and explicit dataset work budgets.
  2. Friendlier data structure — SnapshotDB is produced by a full allocator replay, not a pickle flattening: post-event allocated/active/reserved counters, explicit allocEventId -> freeEventId block lifecycles, dynamic vs. preexisting/static separation, deduplicated callstacks, and lossless ordered (filename, line, name) frames.
  3. Analysis depth — the 13 parameterized query templates (Basic / Statistical / Business), same-event reserved - active gap analysis, peak callstack attribution with coverage, leak-candidate and lifetime forensics, and report memory-tree single-file interactive HTML flamegraphs.
  4. Agent-native CLI — no MCP server; self-discoverable capabilities / --template-info contracts with units, denominators, sentinels and interpretation limits; --stack-bytes context budgeting with retrievable identities; honest has_more/truncated/total_is_exact flags; strict parameter validation with structured --json error envelopes; and the six bundled diagnostic skills.

Structure of the change

  • Add a Mermaid pipeline diagram (pickle -> allocator replay -> SnapshotDB -> templates / reports / skills / Python API).
  • Add a "Why pt-snap?" comparison table against raw pickles, ad-hoc scripts and static HTML dumps.
  • Add the full template/command catalog and a bundled-skill role table.
  • Keep all existing onboarding content: Start Here routing, PyPI-first install, trusted-pickle warning, import/focus write semantics, first report example, --json coverage list, dataset limits, and the agent/collection notes.

🔗 Related Issue

N/A

🧪 Testing

  • Tests added/updated
  • Manual testing completed

Verified render and contract, without running import/install/publication:

pytest tests/test_docs_onboarding.py tests/test_governance.py   # 56 passed
git diff --check

Covered gates:

  • All relative links and heading anchors in README.md / README_zh.md resolve.
  • PyPI install still precedes the editable/Development path in both files.
  • AGENTS.md#development-and-checks and basedpyright pointers retained.
  • Mermaid diagram and tables only; no executable examples changed, so the documented read-only quickstart path and bilingual command equality are untouched.

✅ Checklist

  • Code follows project guidelines
  • Documentation updated (if applicable)
  • No new warnings introduced
  • Changes tested locally

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.

… 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
codeasier merged commit f876665 into main Oct 31, 2026
13 checks passed
@codeasier
codeasier deleted the docs/homepage-value-proposition branch October 31, 2026 17:13
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.
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.

1 participant