Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ jobs:
pip-${{ runner.os }}-${{ matrix.python-version }}-

- name: Install dependencies
run: pip install -e .[dev]
run: pip install -e .[dev,memsnapdump]

- name: Run tests with coverage
run: pytest --cov --cov-report=xml --cov-report=term-missing
Expand Down
9 changes: 9 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,14 @@ pip install -e .

## Quick Start

To start from a raw PyTorch memory snapshot, install the optional MemSnapDump integration from local source, import the pickle into a SnapshotDB, then list the available query templates:

```bash
pip install -e ".[memsnapdump]"
pt-snap import snapshot.pkl
pt-snap query --list
```

```bash
# Set the snapshot database and device
pt-snap focus examples/snapshot_expandable.pkl.db --device 0
Expand All @@ -33,6 +41,7 @@ See the [full quick start guide](docs/en/quickstart.md) for a walkthrough.
| Command | Description |
|---------|-------------|
| `pt-snap focus` | Set and manage analysis focus (database + device) |
| `pt-snap import <snapshot.pkl>` | Import a PyTorch memory snapshot pickle into a SnapshotDB |
| `pt-snap query` | Run memory analysis queries |
| `pt-snap config` | Manage global configuration |
| `pt-snap-mcp` | Start the MCP server for agent integration |
Expand Down
19 changes: 19 additions & 0 deletions docs/en/database.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,25 @@ SnapshotDB is the SQLite database format for persisting PyTorch memory profiling

---

## Producing a snapshot DB

`pt-snap` analyzes SQLite SnapshotDB files. If you start with a raw PyTorch memory snapshot pickle, install the optional MemSnapDump integration from local source and import the snapshot:

```bash
pip install -e ".[memsnapdump]"
pt-snap import snapshot.pkl
```

The import command uses [codeasier/MemSnapDump](https://github.com/codeasier/MemSnapDump) to produce `snapshot.pkl.db` next to the input file by default, then updates project focus so subsequent commands can use it directly:

```bash
pt-snap query --list
```

You can also generate the same SnapshotDB format with the `memsnapdump` package directly, then point `pt-snap focus` at the resulting `.db` file.

---

## Database Structure

### Tables
Expand Down
10 changes: 10 additions & 0 deletions docs/en/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,16 @@ pip install -e .

## Your First Analysis

### Optional: Import a PyTorch Snapshot

If you have a raw `.pkl` memory snapshot, install the optional integration and import it first:

```bash
pip install -e ".[memsnapdump]"
pt-snap import snapshot.pkl
pt-snap query --list
```

### Step 1: Set the Snapshot Database and Device

Point `pt-snap` to your SQLite snapshot database file:
Expand Down
10 changes: 10 additions & 0 deletions docs/zh/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,16 @@ pip install -e .

## 第一次分析

### 可选:导入 PyTorch 快照

如果你手上是原始 `.pkl` 内存快照,请先安装可选集成并导入:

```bash
pip install -e ".[memsnapdump]"
pt-snap import snapshot.pkl
pt-snap query --list
```

### 第一步:设置快照数据库和设备

将 `pt-snap` 指向你的 SQLite 快照数据库文件:
Expand Down
3 changes: 3 additions & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,9 @@ dev = [
"build>=1.0.0",
"basedpyright>=1.39.3",
]
memsnapdump = [
"memsnapdump @ git+https://github.com/codeasier/MemSnapDump.git@master",

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

这里用的是 @master,但 PR 描述和文档里写的是 @main。如果上游默认分支已经是 main,这个 optional dependency 会直接安装失败。建议统一 pyproject.toml、文档和 PR 描述中的分支名。

]
rag = [
"chromadb>=0.4.0",
"langchain>=0.1.0",
Expand Down
43 changes: 43 additions & 0 deletions src/pt_snap_cli/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,49 @@ def focus_database(
_error(str(e))


@app.command("import")
def import_snapshot(
snapshot_file: Annotated[Path, typer.Argument(help="Path to .pkl snapshot")],
output_dir: Annotated[Path | None, typer.Option("--output-dir", "-o")] = None,
device: Annotated[int | None, typer.Option("--device", "-d")] = None,
no_focus: Annotated[bool, typer.Option("--no-focus", help="Skip focus update")] = False,
) -> None:
"""Import a PyTorch memory snapshot into a SQLite database."""
from pt_snap_cli.core.errors import (
DatabaseSchemaError,
FocusFileInvalidError,
ImportExecutionError,
ImportToolMissingError,
SnapshotFileInvalidError,
)
from pt_snap_cli.core.import_service import ImportService
from pt_snap_cli.core.models import ImportOptions

try:
result = ImportService().import_snapshot(
ImportOptions(
snapshot_file=snapshot_file,
output_dir=output_dir,
device=device,
set_focus=not no_focus,
)
)
except (
ImportToolMissingError,
ImportExecutionError,
SnapshotFileInvalidError,
FocusFileInvalidError,
DatabaseSchemaError,
) as e:
_error(str(e))

typer.echo(f"Imported: {result.db_path}")
if result.focus_state is not None:
focus_file = getattr(result.focus_state, "focus_file", None)
if focus_file is not None:
typer.echo(f"Focus: {focus_file}")


@app.command("query")
def query_database(
db_path: Annotated[
Expand Down
4 changes: 4 additions & 0 deletions src/pt_snap_cli/context.py
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,10 @@ def device_ids(self) -> list[int]:
self._device_ids = self._discover_device_ids()
return self._device_ids

def discover_devices(self) -> list[int]:
"""Discover device IDs available in the database."""
return self.device_ids

def _discover_device_ids(self) -> list[int]:
"""Discover device IDs from database table names."""
device_ids = set()
Expand Down
8 changes: 8 additions & 0 deletions src/pt_snap_cli/core/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,18 @@
DatabaseSchemaError,
FocusFileInvalidError,
FocusNotConfiguredError,
ImportExecutionError,
ImportToolMissingError,
InvalidCategoryError,
InvalidDeviceError,
PtSnapCoreError,
QueryExecutionError,
SnapshotFileInvalidError,
TemplateNotFoundError,
TemplateRenderError,
)
from pt_snap_cli.core.focus_service import FocusService
from pt_snap_cli.core.import_service import ImportService
from pt_snap_cli.core.models import (
FocusState,
PeakMemoryReport,
Expand All @@ -34,6 +38,9 @@
"TemplateNotFoundError",
"TemplateRenderError",
"QueryExecutionError",
"ImportToolMissingError",
"SnapshotFileInvalidError",
"ImportExecutionError",
"ResolvedFocus",
"FocusState",
"TemplateParameter",
Expand All @@ -42,6 +49,7 @@
"QueryResult",
"PeakMemoryReport",
"FocusService",
"ImportService",
"QueryService",
"ReportService",
]
12 changes: 12 additions & 0 deletions src/pt_snap_cli/core/errors.py
Original file line number Diff line number Diff line change
Expand Up @@ -36,3 +36,15 @@ class TemplateRenderError(PtSnapCoreError):

class QueryExecutionError(PtSnapCoreError):
pass


class ImportToolMissingError(PtSnapCoreError):
pass


class SnapshotFileInvalidError(PtSnapCoreError):
pass


class ImportExecutionError(PtSnapCoreError):
pass
119 changes: 119 additions & 0 deletions src/pt_snap_cli/core/import_service.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
from __future__ import annotations

import pickle
from pathlib import Path
from typing import TYPE_CHECKING, Any

from pt_snap_cli.core.errors import (
ImportExecutionError,
ImportToolMissingError,
SnapshotFileInvalidError,
)
from pt_snap_cli.core.models import ImportOptions, ImportResult

if TYPE_CHECKING:
from pt_snap_cli.core.focus_service import FocusService

VALID_SUFFIXES = {".pkl", ".pickle"}

try:
from memsnapdump.tools.adaptors.snapshot2db import ( # pyright: ignore[reportMissingImports]
run_dump_to_db as _upstream_run_dump_to_db,
)
except ImportError:
_upstream_run_dump_to_db: Any = None


class ImportService:
"""Import PyTorch snapshot pickle files through the source-integrated MemSnapDump API.

The upstream tool is imported lazily at module load so this package can still be
imported without the optional dependency. All upstream execution goes through a
single private call point for testability. There is intentionally no subprocess
fallback because this PR integrates against MemSnapDump source directly, not a
published PyPI command contract.
"""

def __init__(self, focus_service: FocusService | None = None) -> None:
self._focus_service = focus_service

def import_snapshot(self, options: ImportOptions) -> ImportResult:
self._validate_snapshot_file(options.snapshot_file)
output_dir = self._resolve_output_dir(options.snapshot_file, options.output_dir)

if _upstream_run_dump_to_db is None:
raise ImportToolMissingError(
"memsnapdump package is required; install with pip install -e .[memsnapdump] "
"(or pip install /tmp/MemSnapDump)"
)

try:
self._run_dump_to_db(
snapshot_file=str(options.snapshot_file),
dump_dir=str(output_dir),
device=options.device,
)
except TypeError as exc:
# Monkeypatched / misconfigured call point -> treat as missing tool.
if "NoneType" in str(exc) and "not callable" in str(exc):
raise ImportToolMissingError(
"memsnapdump call point is unavailable; install with "
"pip install -e .[memsnapdump]"
) from exc
raise ImportExecutionError(f"memsnapdump run_dump_to_db failed: {exc}") from exc
except Exception as exc:
raise ImportExecutionError(f"memsnapdump run_dump_to_db failed: {exc}") from exc

db_path = output_dir / (options.snapshot_file.name + ".db")
if not db_path.is_file():
raise ImportExecutionError(f"Expected database not produced: {db_path}")

focus_state = None
if options.set_focus:
if self._focus_service is None:
from pt_snap_cli.core.focus_service import FocusService

self._focus_service = FocusService()
focus_state = self._focus_service.set_project_focus(
db_path=db_path,
device_id=options.device,
base_dir=output_dir,

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

这里把 base_dir 设为 output_dir,会导致 focus 写到输出 DB 所在目录,而不是用户当前项目目录。比如在项目目录执行 pt-snap import /tmp/snapshot.pkl 时,后续从项目目录运行 pt-snap query 可能找不到刚写入的 focus,这和 PR 描述里“后续无需重复指定路径”的目标不一致。建议让 CLI 显式传入当前工作目录作为 project base,或者调整 set_project_focus 的默认语义。

)

return ImportResult(db_path=db_path, device_id=options.device, focus_state=focus_state)

def _run_dump_to_db(
self,
snapshot_file: str,
dump_dir: str,
device: int | None,
) -> bool:
kwargs: dict[str, Any] = {"snapshot_file": snapshot_file, "dump_dir": dump_dir}
if device is not None:
kwargs["device"] = device
assert _upstream_run_dump_to_db is not None # checked by import_snapshot
return _upstream_run_dump_to_db(**kwargs)

@staticmethod
def _validate_snapshot_file(path: Path) -> None:
if not path.exists():
raise SnapshotFileInvalidError(f"Snapshot file does not exist: {path}")
if not path.is_file():
raise SnapshotFileInvalidError(f"Snapshot path is not a file: {path}")
if path.suffix.lower() not in VALID_SUFFIXES:
raise SnapshotFileInvalidError(
f"Snapshot suffix must be .pkl or .pickle, got {path.suffix!r}"
)
try:
with path.open("rb") as file:
obj = pickle.load(file)
except Exception as exc:
raise SnapshotFileInvalidError(f"Cannot unpickle snapshot file: {exc}") from exc
if not isinstance(obj, dict):
raise SnapshotFileInvalidError(
f"Snapshot top-level must be a dict, got {type(obj).__name__}"
)

@staticmethod
def _resolve_output_dir(snapshot_file: Path, output_dir: Path | None) -> Path:
return output_dir.resolve() if output_dir is not None else snapshot_file.resolve().parent
15 changes: 15 additions & 0 deletions src/pt_snap_cli/core/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -69,3 +69,18 @@ class PeakMemoryReport:
peak: dict[str, Any]
allocator_gap: dict[str, Any] | None
callstack_groups: list[dict[str, Any]]


@dataclass(frozen=True)
class ImportOptions:
snapshot_file: Path
output_dir: Path | None = None
device: int | None = None
set_focus: bool = True


@dataclass(frozen=True)
class ImportResult:
db_path: Path
device_id: int | None
focus_state: FocusState | None
Empty file added tests/core/__init__.py
Empty file.
18 changes: 18 additions & 0 deletions tests/core/test_import_errors.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
from pt_snap_cli.core import (
ImportExecutionError,
ImportToolMissingError,
PtSnapCoreError,
SnapshotFileInvalidError,
)


def test_import_tool_missing_error_is_pt_snap_core():
assert issubclass(ImportToolMissingError, PtSnapCoreError)


def test_snapshot_file_invalid_error_is_pt_snap_core():
assert issubclass(SnapshotFileInvalidError, PtSnapCoreError)


def test_import_execution_error_is_pt_snap_core():
assert issubclass(ImportExecutionError, PtSnapCoreError)
Loading
Loading