diff --git a/.github/AGENTS.md b/.github/AGENTS.md index 4e5e4ae..774af97 100644 --- a/.github/AGENTS.md +++ b/.github/AGENTS.md @@ -1,8 +1,10 @@ - + # .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. diff --git a/.github/ISSUE_TEMPLATE/AGENTS.md b/.github/ISSUE_TEMPLATE/AGENTS.md index 604ab3b..5d96b14 100644 --- a/.github/ISSUE_TEMPLATE/AGENTS.md +++ b/.github/ISSUE_TEMPLATE/AGENTS.md @@ -1,8 +1,10 @@ - + # 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. diff --git a/.github/workflows/AGENTS.md b/.github/workflows/AGENTS.md index c4d38d7..75cbe58 100644 --- a/.github/workflows/AGENTS.md +++ b/.github/workflows/AGENTS.md @@ -1,8 +1,10 @@ - + # workflows +Parent scope: [.github](../AGENTS.md) + ## Purpose `workflows` contains GitHub Actions definitions for continuous integration and release automation. diff --git a/AGENTS.md b/AGENTS.md index 5e9f6ff..82a13cb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 @@ -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 | diff --git a/benchmarks/AGENTS.md b/benchmarks/AGENTS.md index b87f273..2e636ff 100644 --- a/benchmarks/AGENTS.md +++ b/benchmarks/AGENTS.md @@ -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 diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 498bb61..899d592 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -1,8 +1,10 @@ - + # 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. diff --git a/docs/en/AGENTS.md b/docs/en/AGENTS.md index a18e379..c1e319e 100644 --- a/docs/en/AGENTS.md +++ b/docs/en/AGENTS.md @@ -1,8 +1,10 @@ - + # 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. diff --git a/docs/zh/AGENTS.md b/docs/zh/AGENTS.md index 9199b91..c661449 100644 --- a/docs/zh/AGENTS.md +++ b/docs/zh/AGENTS.md @@ -1,8 +1,10 @@ - + # 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. diff --git a/skills/AGENTS.md b/skills/AGENTS.md index 567d064..b4b9afa 100644 --- a/skills/AGENTS.md +++ b/skills/AGENTS.md @@ -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 diff --git a/src/AGENTS.md b/src/AGENTS.md index d75e13f..d88bd39 100644 --- a/src/AGENTS.md +++ b/src/AGENTS.md @@ -1,8 +1,10 @@ - + # 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. diff --git a/src/pt_snap_cli/AGENTS.md b/src/pt_snap_cli/AGENTS.md index 01ffa9b..bddba02 100644 --- a/src/pt_snap_cli/AGENTS.md +++ b/src/pt_snap_cli/AGENTS.md @@ -1,8 +1,10 @@ - + # 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. diff --git a/src/pt_snap_cli/core/AGENTS.md b/src/pt_snap_cli/core/AGENTS.md index 0eeeba3..e22a586 100644 --- a/src/pt_snap_cli/core/AGENTS.md +++ b/src/pt_snap_cli/core/AGENTS.md @@ -1,8 +1,10 @@ - + # 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. diff --git a/src/pt_snap_cli/mcp/AGENTS.md b/src/pt_snap_cli/mcp/AGENTS.md index d17c116..ae2c6b2 100644 --- a/src/pt_snap_cli/mcp/AGENTS.md +++ b/src/pt_snap_cli/mcp/AGENTS.md @@ -1,8 +1,10 @@ - + # 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. diff --git a/src/pt_snap_cli/models/AGENTS.md b/src/pt_snap_cli/models/AGENTS.md index bf64046..43539d1 100644 --- a/src/pt_snap_cli/models/AGENTS.md +++ b/src/pt_snap_cli/models/AGENTS.md @@ -1,8 +1,10 @@ - + # 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. diff --git a/src/pt_snap_cli/query/AGENTS.md b/src/pt_snap_cli/query/AGENTS.md index ba1595a..0453742 100644 --- a/src/pt_snap_cli/query/AGENTS.md +++ b/src/pt_snap_cli/query/AGENTS.md @@ -1,8 +1,10 @@ - + # 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. diff --git a/src/pt_snap_cli/query/templates/AGENTS.md b/src/pt_snap_cli/query/templates/AGENTS.md index 2699728..e251c6b 100644 --- a/src/pt_snap_cli/query/templates/AGENTS.md +++ b/src/pt_snap_cli/query/templates/AGENTS.md @@ -1,8 +1,10 @@ - + # 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. diff --git a/src/pt_snap_cli/snapshot/AGENTS.md b/src/pt_snap_cli/snapshot/AGENTS.md index a1e2f72..5404c62 100644 --- a/src/pt_snap_cli/snapshot/AGENTS.md +++ b/src/pt_snap_cli/snapshot/AGENTS.md @@ -1,8 +1,10 @@ - + # 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/`. diff --git a/tests/AGENTS.md b/tests/AGENTS.md index 09f9885..dea678c 100644 --- a/tests/AGENTS.md +++ b/tests/AGENTS.md @@ -1,8 +1,10 @@ - + # 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/`. diff --git a/tests/core/AGENTS.md b/tests/core/AGENTS.md index 4ef7b7d..dd9c3ef 100644 --- a/tests/core/AGENTS.md +++ b/tests/core/AGENTS.md @@ -1,8 +1,10 @@ - + # 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. diff --git a/tests/fixtures/AGENTS.md b/tests/fixtures/AGENTS.md index ba764ea..c3f7d7c 100644 --- a/tests/fixtures/AGENTS.md +++ b/tests/fixtures/AGENTS.md @@ -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 diff --git a/tests/query/AGENTS.md b/tests/query/AGENTS.md index 24a0819..c2907af 100644 --- a/tests/query/AGENTS.md +++ b/tests/query/AGENTS.md @@ -1,8 +1,10 @@ - + # 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. diff --git a/tests/snapshot/AGENTS.md b/tests/snapshot/AGENTS.md index 4883483..8d78423 100644 --- a/tests/snapshot/AGENTS.md +++ b/tests/snapshot/AGENTS.md @@ -1,8 +1,10 @@ - + # 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.