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
4 changes: 3 additions & 1 deletion .github/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-08 -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-24 -->

# .github

Parent scope: [repository root](../AGENTS.md)

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

Expand Down
4 changes: 3 additions & 1 deletion .github/ISSUE_TEMPLATE/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-09 -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-24 -->

# ISSUE_TEMPLATE

Parent scope: [.github](../AGENTS.md)

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

Expand Down
4 changes: 3 additions & 1 deletion .github/workflows/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-08 -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-24 -->

# workflows

Parent scope: [.github](../AGENTS.md)

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

Expand Down
25 changes: 23 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ Run these commands from the repository root.
- Lint: `ruff check .`
- Check formatting: `black --check .`
- Apply formatting: `black .`
- Type check: `basedpyright` (CI runs it on the files selected by `[tool.basedpyright] include` in `pyproject.toml`)

`tests/run_tests.sh` is tied to a developer-specific Conda path and writes
coverage reports under `test_reports/`; use direct `pytest` commands unless
Expand All @@ -37,13 +38,33 @@ that local environment is intentionally available.
| Benchmarks | [benchmarks/AGENTS.md](benchmarks/AGENTS.md) | Import and SQLite performance measurement with temporary outputs |
| Setup skill | [skills/AGENTS.md](skills/AGENTS.md) | Installation skill approval and active-interpreter safety boundary |

Deeper scoped guides nested under the entries above:

| Scope | Guide | Responsibility |
| --- | --- | --- |
| Package root | [src/pt_snap_cli/AGENTS.md](src/pt_snap_cli/AGENTS.md) | Package layout, entry modules (`cli.py`, `api.py`, `context.py`, `config.py`), and submodule routing |
| Product services | [src/pt_snap_cli/core/AGENTS.md](src/pt_snap_cli/core/AGENTS.md) | Focus, import, split, metadata, query, and report service contracts |
| Query subsystem | [src/pt_snap_cli/query/AGENTS.md](src/pt_snap_cli/query/AGENTS.md) | YAML templates, registry, executor, builder/condition SQL helpers, and result mapping |
| Query templates | [src/pt_snap_cli/query/templates/AGENTS.md](src/pt_snap_cli/query/templates/AGENTS.md) | Packaged YAML template authoring and category conventions |
| Snapshot runtime | [src/pt_snap_cli/snapshot/AGENTS.md](src/pt_snap_cli/snapshot/AGENTS.md) | First-party pickle/JSON representation, replay, database import, and slicing |
| MCP server | [src/pt_snap_cli/mcp/AGENTS.md](src/pt_snap_cli/mcp/AGENTS.md) | FastMCP entrypoint, tools, and resources |
| Domain models | [src/pt_snap_cli/models/AGENTS.md](src/pt_snap_cli/models/AGENTS.md) | Dataclass models and allocator event/block enums |
| CI and release workflows | [.github/workflows/AGENTS.md](.github/workflows/AGENTS.md) | Reusable quality workflow and tag-gated release publication |
| Issue templates | [.github/ISSUE_TEMPLATE/AGENTS.md](.github/ISSUE_TEMPLATE/AGENTS.md) | Issue forms and snapshot-runtime provenance decision capture |
| English docs | [docs/en/AGENTS.md](docs/en/AGENTS.md) | English user guides and API references |
| Chinese docs | [docs/zh/AGENTS.md](docs/zh/AGENTS.md) | Chinese user guides kept behaviorally aligned with `docs/en/` |
| Core service tests | [tests/core/AGENTS.md](tests/core/AGENTS.md) | Focus, import, split, metadata, query, and report service suites |
| Query tests | [tests/query/AGENTS.md](tests/query/AGENTS.md) | Query config, registry, executor, builder, and mapper suites |
| Snapshot runtime tests | [tests/snapshot/AGENTS.md](tests/snapshot/AGENTS.md) | Replay, slicing, database import, and entity runtime suites |
| Executable fixtures | [tests/fixtures/AGENTS.md](tests/fixtures/AGENTS.md) | Reviewed pickle fixtures and provenance gating |

## Runtime Topology

| Surface | Entry point | Responsibility |
| --- | --- | --- |
| CLI | `src/pt_snap_cli/cli.py` via `pt_snap_cli.cli:_safe_call` | Typer commands for focus, import, split, metadata, query, reports, and config |
| CLI | `src/pt_snap_cli/cli.py`, installed as `pt-snap` (`pt_snap_cli.cli:_safe_call`) | Typer commands for focus, import, split, metadata, query, and config, plus the `report` group (`pt-snap report peak-memory`) |
| Python API | `src/pt_snap_cli/api.py` (`SnapshotAnalyzer`) | Programmatic focus, query, and metadata facade |
| MCP | `src/pt_snap_cli/mcp/server.py` via `pt_snap_cli.mcp.server:main` | Agent tools/resources backed by `SnapshotAnalyzer` |
| MCP | `src/pt_snap_cli/mcp/server.py`, installed as `pt-snap-mcp` (`pt_snap_cli.mcp.server:main`) | Agent tools/resources backed by `SnapshotAnalyzer` |
| Product services | `src/pt_snap_cli/core/` | Shared focus, import, split, query, report, metadata, and error semantics |
| Database access | `src/pt_snap_cli/context.py` | Read-only SQLite validation, connection management, and device discovery |
| Query engine | `src/pt_snap_cli/query/` | YAML loading, registry, parameter validation, SQL rendering/execution, and result mapping |
Expand Down
2 changes: 2 additions & 0 deletions benchmarks/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

# benchmarks

Parent scope: [repository root](../AGENTS.md)

## Purpose
`benchmarks` contains opt-in performance measurements. These scripts are not
pytest entry points: they can consume substantial CPU, memory, and time, and the
Expand Down
4 changes: 3 additions & 1 deletion docs/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-08 -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-24 -->

# docs

Parent scope: [repository root](../AGENTS.md)

## Purpose
`docs` contains end-user and API documentation for the CLI, focus management, query templates, MCP integration, snapshot database format, high-level and result mapping Python APIs, and retained legal evidence. It is split into English and Chinese language trees with a top-level README for navigation.

Expand Down
4 changes: 3 additions & 1 deletion docs/en/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-08 -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-24 -->

# en

Parent scope: [docs](../AGENTS.md)

## Purpose
`docs/en` contains the English documentation set for installing and using `pt-snap-cli`, managing focus, querying and splitting snapshots, running the MCP server, understanding the SQLite schema, and using the high-level and result mapping Python APIs.

Expand Down
4 changes: 3 additions & 1 deletion docs/zh/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-08 -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-24 -->

# zh

Parent scope: [docs](../AGENTS.md); translation reference: [en](../en/AGENTS.md)

## Purpose
`docs/zh` contains the Chinese documentation set for `pt-snap-cli`, covering the same user-facing areas as the English docs: quick start, focus management, querying, snapshot splitting, MCP integration, database schema, and the high-level and result mapping Python APIs.

Expand Down
2 changes: 2 additions & 0 deletions skills/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

# skills

Parent scope: [repository root](../AGENTS.md)

## Purpose
`skills` contains agent workflows shipped with the repository. The setup skill
has an independent side-effect boundary because it may install packages into the
Expand Down
4 changes: 3 additions & 1 deletion src/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-08 -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-24 -->

# src

Parent scope: [repository root](../AGENTS.md)

## Purpose
`src` contains the installable Python package for `pt-snap-cli`. Its only package subtree, `pt_snap_cli`, holds the CLI, MCP server, product services, query system, first-party snapshot runtime, and domain models shipped in the distribution.

Expand Down
4 changes: 3 additions & 1 deletion src/pt_snap_cli/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-08 -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-24 -->

# pt_snap_cli

Parent scope: [src](../AGENTS.md)

## Purpose
`pt_snap_cli` is the main Python package. It exposes the Typer CLI, programmatic `SnapshotAnalyzer` API, read-only SQLite context, focus configuration, product service layer, MCP server, domain models, YAML-driven query execution pipeline, and first-party snapshot runtime.

Expand Down
4 changes: 3 additions & 1 deletion src/pt_snap_cli/core/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-08 -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-24 -->

# core

Parent scope: [pt_snap_cli package](../AGENTS.md)

## Purpose
`core` contains the product service layer shared by CLI, Python API, and MCP adapters. It owns focus, import publication and metadata, snapshot splitting, query orchestration, reports, stable result models, and domain-specific errors over lower-level config, context, query, and snapshot modules.

Expand Down
4 changes: 3 additions & 1 deletion src/pt_snap_cli/mcp/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-08 -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-24 -->

# mcp

Parent scope: [pt_snap_cli package](../AGENTS.md)

## Purpose
`mcp` exposes `pt-snap-cli` functionality as a FastMCP server so agents and MCP clients can inspect or set focus, list templates, fetch template metadata, execute queries, inspect database import metadata, and use a memory-leak analysis prompt.

Expand Down
4 changes: 3 additions & 1 deletion src/pt_snap_cli/models/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-05-26 | Updated: 2026-05-26 -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-24 -->

# models

Parent scope: [pt_snap_cli package](../AGENTS.md)

## Purpose
`models` contains library-facing domain objects for PyTorch memory snapshot data, including allocation blocks, events, and enum values that describe allocator state and event types.

Expand Down
4 changes: 3 additions & 1 deletion src/pt_snap_cli/query/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-09 -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-24 -->

# query

Parent scope: [pt_snap_cli package](../AGENTS.md)

## Purpose
`query` implements the template-driven query subsystem. It loads YAML query definitions, validates template parameters, renders device-specific SQL with Jinja2, executes queries through the read-only database context, maps result types, and provides fluent builder utilities for constructing SQL programmatically.

Expand Down
4 changes: 3 additions & 1 deletion src/pt_snap_cli/query/templates/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-09 -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-24 -->

# templates

Parent scope: [query subsystem](../AGENTS.md)

## Purpose
`templates` contains the packaged YAML query templates used by the registry and CLI/API/MCP query execution. Templates are grouped by category and define metadata, parameters, SQL, and output schemas.

Expand Down
4 changes: 3 additions & 1 deletion src/pt_snap_cli/snapshot/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-08-08 | Updated: 2026-08-08 -->
<!-- Generated: 2026-08-08 | Updated: 2026-08-24 -->

# snapshot

Parent scope: [pt_snap_cli package](../AGENTS.md)

## Purpose
`snapshot` is the first-party runtime for trusted PyTorch memory snapshot representations. It owns pickle/JSON normalization, allocator replay, SnapshotDB adaptation, and replay-safe slicing; CLI/API product contracts remain in `core/`.

Expand Down
4 changes: 3 additions & 1 deletion tests/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-08 -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-24 -->

# tests

Parent scope: [repository root](../AGENTS.md)

## Purpose
`tests` contains the pytest suite for CLI/API/MCP contracts, configuration, services, query behavior, packaging/governance, and the first-party snapshot runtime. Most tests use temporary data; snapshot and import suites may use only checksum-verified executable fixtures under `tests/fixtures/snapshots/`.

Expand Down
4 changes: 3 additions & 1 deletion tests/core/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-08 -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-24 -->

# core tests

Parent scope: [tests](../AGENTS.md)

## Purpose
`tests/core` verifies focus, import, split, metadata, query, and report services between CLI/API/MCP callers and lower-level config, context, query, and snapshot modules.

Expand Down
2 changes: 2 additions & 0 deletions tests/fixtures/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

# fixtures

Parent scope: [tests](../AGENTS.md)

## Purpose
`tests/fixtures` owns committed test inputs. Snapshot pickle files are executable
inputs with a separate acceptance lifecycle; they are not trusted merely because
Expand Down
4 changes: 3 additions & 1 deletion tests/query/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-08 -->
<!-- Generated: 2026-05-26 | Updated: 2026-08-24 -->

# query tests

Parent scope: [tests](../AGENTS.md)

## Purpose
`tests/query` verifies the query subsystem: fluent SQL building, condition composition, YAML config loading, Jinja2 rendering, SQLite execution, result mapping, and registry behavior.

Expand Down
4 changes: 3 additions & 1 deletion tests/snapshot/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-08-08 | Updated: 2026-08-08 -->
<!-- Generated: 2026-08-08 | Updated: 2026-08-24 -->

# snapshot tests

Parent scope: [tests](../AGENTS.md)

## Purpose
`tests/snapshot` verifies the first-party snapshot representation, entities, allocator simulation/replay, SQLite adaptors, and slice runtime using synthetic objects and checksum-verified fixtures.

Expand Down
Loading