Skip to content
Merged
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
46 changes: 46 additions & 0 deletions .github/AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-08 -->

# .github

## Purpose
`.github` contains GitHub project automation: issue forms, pull request templates, snapshot provenance enforcement, release workflow, and CI verification definitions.

## Key Files
| File | Description |
|------|-------------|
| None | GitHub metadata is organized in subdirectories. |

## Subdirectories
| Directory | Purpose |
|-----------|---------|
| `ISSUE_TEMPLATE/` | Structured issue form YAML files (see `ISSUE_TEMPLATE/AGENTS.md`). |
| `PULL_REQUEST_TEMPLATE/` | Pull request description template (see `PULL_REQUEST_TEMPLATE/AGENTS.md`). |
| `scripts/` | Repository governance scripts, including snapshot provenance validation. |
| `workflows/` | GitHub Actions workflow definitions (see `workflows/AGENTS.md`). |

## For AI Agents

### Working In This Directory
- Treat workflow changes as CI-affecting; keep dependency installation and verification commands aligned with `pyproject.toml`.
- Keep issue and PR templates concise and consistent with repository scope.

### Testing Requirements
- Validate YAML syntax for workflow or issue template edits.
- For workflow changes, mirror commands locally where practical before relying on CI.
- Run `pytest tests/test_governance.py` when provenance scripts, workflow wiring, or PR declarations change.

### Common Patterns
- CI installs the package with development dependencies and runs lint/type/test checks.
- Snapshot runtime changes require one validated provenance decision from the PR body.

## Dependencies

### Internal
- `pyproject.toml` defines the Python versions, package dependencies, and tools invoked by workflows.
- `tests/` contains the suite run by CI.

### External
- GitHub Actions runners and standard GitHub issue/PR template formats.

<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->
43 changes: 43 additions & 0 deletions .github/ISSUE_TEMPLATE/AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-05-26 | Updated: 2026-05-26 -->

# ISSUE_TEMPLATE

## Purpose
`ISSUE_TEMPLATE` contains structured GitHub issue forms for bugs, documentation requests, feature requests, questions, and template chooser configuration.

## Key Files
| File | Description |
|------|-------------|
| `bug_report.yaml` | Form for reproducible defects and environment details. |
| `config.yaml` | GitHub issue template chooser configuration. |
| `documentation.yaml` | Form for documentation improvements or corrections. |
| `feature_request.yaml` | Form for proposed enhancements. |
| `question.yaml` | Form for usage questions. |

## Subdirectories
| Directory | Purpose |
|-----------|---------|
| None | Issue templates are flat YAML files. |

## For AI Agents

### Working In This Directory
- Keep issue forms scoped to this Python CLI/MCP project.
- Preserve valid GitHub issue form YAML structure.

### Testing Requirements
- Validate YAML syntax after edits.

### Common Patterns
- Forms collect structured fields rather than relying on free-form Markdown only.

## Dependencies

### Internal
- Repository README/docs provide canonical terminology for issue prompts.

### External
- GitHub issue form YAML schema.

<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->
42 changes: 42 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE/AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-08 -->

# PULL_REQUEST_TEMPLATE

## Purpose
`PULL_REQUEST_TEMPLATE` contains the default pull request description template used for repository contributions.

## Key Files
| File | Description |
|------|-------------|
| `pull_request_template.md` | PR body template for summaries, testing, and review context. |

## Subdirectories
| Directory | Purpose |
|-----------|---------|
| None | PR template content is flat. |

## For AI Agents

### Working In This Directory
- Keep checklist items aligned with current verification expectations.
- Avoid adding process requirements that CI or project documentation does not support.
- Preserve the exact snapshot provenance decision/reason labels parsed by `.github/scripts/check_snapshot_provenance.py`.

### Testing Requirements
- Review Markdown rendering after edits.
- Run `pytest tests/test_governance.py` when changing provenance declarations.

### Common Patterns
- The template should prompt contributors for what changed and how it was tested.
- Snapshot runtime changes require exactly one `updated` or `no-update` decision; `no-update` also requires a specific reason.

## Dependencies

### Internal
- `.github/workflows/` defines automated checks referenced by PR guidance.

### External
- GitHub pull request template Markdown support.

<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->
46 changes: 46 additions & 0 deletions .github/workflows/AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-08 -->

# workflows

## Purpose
`workflows` contains GitHub Actions definitions for continuous integration and release automation.

## Key Files
| File | Description |
|------|-------------|
| `test.yml` | PR provenance gate plus lint, type, test-matrix, coverage, build, and wheel smoke checks. |
| `release.yml` | Release workflow for building and publishing package artifacts. |

## Subdirectories
| Directory | Purpose |
|-----------|---------|
| None | Workflow YAML files are flat. |

## For AI Agents

### Working In This Directory
- Keep workflow Python versions and commands aligned with `pyproject.toml`.
- Treat release workflow edits as high-impact and verify syntax carefully.
- Do not bypass tests, lint, type checks, or publishing safeguards without explicit instruction.
- Keep snapshot provenance inputs and declaration parsing aligned with `.github/scripts/check_snapshot_provenance.py` and the PR template.

### Testing Requirements
- Validate YAML syntax.
- Run equivalent local commands when changing CI command sequences.
- Run `pytest tests/test_governance.py tests/test_release_workflow.py` for provenance or release workflow changes.

### Common Patterns
- Workflows install the package with development extras before verification.
- The test workflow defines independent provenance, lint, and Python-version test jobs that may run concurrently.

## Dependencies

### Internal
- `pyproject.toml` defines package metadata, dev extras, and tool configuration.
- `tests/` and source files are exercised by CI.

### External
- GitHub Actions hosted runners and packaging/publishing actions.

<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->
9 changes: 9 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,15 @@ Run these commands from the repository root.
coverage reports under `test_reports/`; use direct `pytest` commands unless
that local environment is intentionally available.

## Scoped Guidance

| Scope | Guide | Responsibility |
| --- | --- | --- |
| GitHub automation | [.github/AGENTS.md](.github/AGENTS.md) | Issue/PR templates, provenance guard, CI, and release workflows |
| User documentation | [docs/AGENTS.md](docs/AGENTS.md) | English/Chinese guides, API docs, navigation, and legal evidence |
| Package source | [src/AGENTS.md](src/AGENTS.md) | Installable package boundaries and source-layout rules |
| Tests | [tests/AGENTS.md](tests/AGENTS.md) | Cross-surface contracts, service/query/runtime suites, and trusted fixtures |

## Runtime Topology

| Surface | Entry point | Responsibility |
Expand Down
72 changes: 9 additions & 63 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ A command-line tool for analyzing PyTorch memory snapshots. Set a snapshot datab

## Installation

From a source checkout:

```bash
pip install -e .
```
Expand All @@ -25,7 +27,7 @@ pt-snap query --list

```bash
# Set the snapshot database and device
pt-snap focus examples/snapshot_expandable.pkl.db --device 0
pt-snap focus snapshot.pkl.db --device 0

# List available queries
pt-snap query --list
Expand Down Expand Up @@ -71,21 +73,12 @@ See the [full quick start guide](docs/en/quickstart.md) for a walkthrough.
pt-snap-mcp
```

The server exposes the following tools:

| Tool | Description |
|------|-------------|
| `get_focus` | Get the current analysis focus |
| `set_focus` | Set focus to a database and optional device |
| `list_templates` | List available query templates |
| `get_template_info` | Get template details and parameters |
| `execute_query` | Run a query template against the focused database |
| `get_database_metadata` | Inspect import metadata for the focused or specified database |

See the [MCP guide](docs/en/mcp.md) for setup and usage details.

## Documentation

See the [documentation index](docs/README.md) for all English and Chinese guides.

| Topic | Guide |
|-------|-------|
| Getting started | [Quick Start](docs/en/quickstart.md) |
Expand All @@ -94,61 +87,14 @@ See the [MCP guide](docs/en/mcp.md) for setup and usage details.
| Splitting snapshots | [Splitting Snapshots](docs/en/splitting.md) |
| MCP server | [MCP Guide](docs/en/mcp.md) |
| Database format | [SnapshotDB Schema](docs/en/database.md) |
| Python API | [ResultMapper API](docs/en/result-mapper-api.md) |

## Query Templates

9 built-in templates across 3 categories:

- **Basic**: `block`, `event`, `allocation`
- **Statistical**: `active_blocks_at_event`, `allocator_gap`, `callstack_analysis`, `memory_peak`
- **Business**: `active_memory_callstack_at_event`, `leak_detection`

See [Querying](docs/en/querying.md) for details.

## Project Structure

```
pt-snap-cli/
├── src/
│ └── pt_snap_cli/
│ ├── cli.py # CLI entry point
│ ├── context.py # Database context manager
│ ├── config.py # Focus management
│ ├── api.py # Python API layer
│ ├── query/
│ │ ├── builder.py # Query builder
│ │ ├── executor.py # Query executor
│ │ ├── mapper.py # Result mapper
│ │ ├── registry.py # Query registry
│ │ ├── condition.py # Query conditions
│ │ ├── config.py # Query configuration
│ │ └── templates/ # Query templates
│ ├── models/ # Data models
│ └── mcp/ # MCP server for agent integration
├── tests/ # Test files
├── examples/ # Example data
└── docs/ # Documentation
```
| Python API | [SnapshotAnalyzer API](docs/en/snapshot-analyzer-api.md) |
| Result mapping utility | [ResultMapper API](docs/en/result-mapper-api.md) |

## Development

```bash
pip install -e ".[dev]" # Install development dependencies
pytest # Run all tests
./tests/run_tests.sh # Full test run with coverage
black . && ruff check . # Format and lint
black --check . && ruff check . # Check formatting and lint
python -m build # Build sdist and wheel
```

### CLI/MCP semantic contract

The CLI and MCP server must keep using the shared API/core services as the single
semantic source of truth. The CLI may render results as terminal text and the MCP
server may return JSON-like tool payloads, but normalized meanings must stay in
sync for focus handling, query template listing, template metadata, query
execution, and shared error cases.

`tests/test_contract_cli_mcp.py` compares normalized CLI output with MCP tool
results on the same inputs and fixtures. When adding a new shared CLI/MCP capability,
update or add a contract case in that file so CI fails if either adapter drifts
from the shared behavior.
59 changes: 9 additions & 50 deletions README_zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@

## 安装

从源码 checkout 安装:

```bash
pip install -e .
```
Expand All @@ -21,7 +23,7 @@ pt-snap import snapshot.pkl
pt-snap metadata snapshot.pkl.db

# 设置快照数据库和设备
pt-snap focus examples/snapshot_expandable.pkl.db --device 0
pt-snap focus snapshot.pkl.db --device 0

# 列出可用查询
pt-snap query --list
Expand Down Expand Up @@ -67,21 +69,12 @@ pt-snap split snapshot.pkl --slices 4 --output snapshot-slices
pt-snap-mcp
```

服务器暴露以下工具:

| 工具 | 说明 |
|------|------|
| `get_focus` | 获取当前分析焦点 |
| `set_focus` | 设置焦点到指定数据库和设备 |
| `list_templates` | 列出可用的查询模板 |
| `get_template_info` | 获取模板详情和参数 |
| `execute_query` | 对焦点数据库执行查询模板 |
| `get_database_metadata` | 查看焦点或指定数据库的导入 metadata |

详见 [MCP 指南](docs/zh/mcp.md)。

## 文档

全部中英文指南见[文档索引](docs/README.md)。

| 主题 | 指南 |
|------|------|
| 入门指南 | [Quick Start](docs/zh/quickstart.md) |
Expand All @@ -90,48 +83,14 @@ pt-snap-mcp
| 拆分快照 | [拆分快照](docs/zh/splitting.md) |
| MCP 服务器 | [MCP 指南](docs/zh/mcp.md) |
| 数据库格式 | [SnapshotDB Schema](docs/zh/database.md) |
| Python API | [ResultMapper API](docs/zh/result-mapper-api.md) |

## 查询模板

9 个内置模板,3 个分类:

- **Basic**: `block`, `event`, `allocation`
- **Statistical**: `active_blocks_at_event`, `allocator_gap`, `callstack_analysis`, `memory_peak`
- **Business**: `active_memory_callstack_at_event`, `leak_detection`

详见 [Querying](docs/zh/querying.md)。

## 项目结构

```
pt-snap-cli/
├── src/
│ └── pt_snap_cli/
│ ├── cli.py # CLI 入口
│ ├── context.py # 数据库连接管理器
│ ├── config.py # 焦点管理
│ ├── api.py # Python API 层
│ ├── query/
│ │ ├── builder.py # 查询构建器
│ │ ├── executor.py # 查询执行器
│ │ ├── mapper.py # 结果映射器
│ │ ├── registry.py # 查询注册表
│ │ ├── condition.py # 查询条件
│ │ ├── config.py # 查询配置
│ │ └── templates/ # 查询模板
│ ├── models/ # 数据模型
│ └── mcp/ # MCP 服务器(Agent 集成)
├── tests/ # 测试文件
├── examples/ # 示例数据
└── docs/ # 文档
```
| Python API | [SnapshotAnalyzer API](docs/zh/snapshot-analyzer-api.md) |
| 结果映射工具 | [ResultMapper API](docs/zh/result-mapper-api.md) |

## 开发

```bash
pip install -e ".[dev]" # 安装开发依赖
pytest # 运行所有测试
./tests/run_tests.sh # 完整测试(含覆盖率)
black . && ruff check . # 格式化和 lint
black --check . && ruff check . # 检查格式和 lint
python -m build # 构建 sdist 和 wheel
```
Loading
Loading