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
7 changes: 3 additions & 4 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,10 +22,9 @@ Run these commands from the repository root.
- Check formatting: `black --check .`
- Apply formatting: `black .`
- Type check: `python -m basedpyright --pythonpath "$(python -c 'import sys; print(sys.executable)')"`
(covers all of `src/pt_snap_cli`; the gate is zero errors and warnings are
informational. `pyproject.toml` downgrades a listed set of rules to warnings
under `src/pt_snap_cli/snapshot/` until its annotations are fixed — do not
widen that list, shrink it)
(covers all of `src/pt_snap_cli`, including `snapshot/`; the gate is zero
errors and warnings are informational. Do not add a snapshot
`executionEnvironments` downgrade.)

`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 Down
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,10 @@
- 已有 `metadata --json`、`report peak-memory --json` 与 `skill list/install/upgrade/uninstall --json` 成功字段保持兼容,不包进新信封。它们在 `--json` 失败时改走 stderr 错误信封。新的 `capabilities --json` 与 `overview --json` 使用 #138 成功/失败信封。`capabilities` 在技能目录不可读时走 `SKILL_ERROR`;`overview` 把损坏的设备表/边界查询翻译为 `DATABASE_SCHEMA_INVALID`,并把损坏的 focus 文件翻译为 `FOCUS_FILE_INVALID`。
- 查询默认 `total` 不再在触达 `-n` 时自动变成匹配集合 `COUNT`。依赖该旧语义的调用方必须显式传 `--exact-total` / `exact_total=True`。

### 稳定性与工程

- basedpyright 对 `src/pt_snap_cli/snapshot/` 与其余包路径同一套 error 门槛:补齐注解后移除 snapshot `executionEnvironments` 降级列表(#122 阶段 3)。
Comment thread
codeasier marked this conversation as resolved.
Resolved

## [0.4.0] - Unreleased

相对 v0.3.0:关闭 MCP 产品面,Agent 集成入口收敛到 bundled skills 与 CLI;并补上 helper 引导技能、查询参数白名单,以及易误读字段的语义元数据。本段覆盖 `v0.3.0` 之后已合入 `main` 的全部用户可见变更。
Expand Down
15 changes: 0 additions & 15 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -103,21 +103,6 @@ include = ["src/pt_snap_cli"]
# to be, which is why the check passed in CI yet failed on developer machines.
failOnWarnings = false

# The snapshot runtime was migrated from its upstream project with its original
# loose annotations (issue #122, phase 3). Only the rules it currently violates are
# downgraded, and only under this root; every other module is checked at error
# level. Remove entries here as the annotations are fixed. Changes under
# src/pt_snap_cli/snapshot/ also require a PROVENANCE.md entry.
[[tool.basedpyright.executionEnvironments]]
root = "src/pt_snap_cli/snapshot"
reportMissingTypeArgument = "warning"
reportAssignmentType = "warning"
reportAttributeAccessIssue = "warning"
reportUninitializedInstanceVariable = "warning"
reportArgumentType = "warning"
reportIndexIssue = "warning"
reportImportCycles = "warning"

[tool.coverage.run]
source = ["pt_snap_cli"]
branch = true
Expand Down
7 changes: 7 additions & 0 deletions src/pt_snap_cli/snapshot/PROVENANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -188,6 +188,13 @@ The upstream standalone split frontend is deliberately excluded, not deferred:
message, and uses a left join with a missing-callstack placeholder in
statistical analysis. These are local fixes to the issue #113 runtime;
audited upstream source mappings and license terms remain unchanged.
- On 2026-09-19, issue #122 phase 3 tightened first-party type annotations in
the snapshot runtime (`dict[str, Any]`, `int | None`, `Literal` defaults,
`DeviceSnapshot.__init__`, and import-cycle-safe submodule imports) so
basedpyright can check `src/pt_snap_cli/snapshot/` at the same error level
as the rest of the package. Call formatting, optional-field defaults, and
replay/import/split behavior are unchanged; audited upstream source mappings
and license terms remain unchanged.

## Migration toolchain

Expand Down
71 changes: 41 additions & 30 deletions src/pt_snap_cli/snapshot/base/entities.py
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
from dataclasses import dataclass, field
from typing import Any, Literal
from typing import Any, Literal, cast


class Frame:
filename: str = ""
line: int = -1
name: str = ""

_origin: dict = None # Readonly
_origin: dict[str, Any] | None = None # Readonly

@classmethod
def from_dict(cls, frame_dict: dict):
def from_dict(cls, frame_dict: dict[str, Any]):
frame = cls()
frame.filename = frame_dict["filename"]
frame.line = frame_dict["line"]
Expand All @@ -26,19 +26,19 @@ def to_dict(self):
)


def _format_callstack(frames: list[Frame] | list[dict]) -> str:
def _format_frame(frame: Frame | dict[str, Any]) -> str:
if isinstance(frame, Frame):
return f"{frame.filename}:{frame.line} {frame.name}"
return f"{frame['filename']}:{frame['line']} {frame['name']}"


def _format_callstack(frames: list[Frame] | list[dict[str, Any]]) -> str:
if not frames:
return ""
if isinstance(frames[0], Frame):
return "\n".join(
[f"{frame.filename}:{frame.line} {frame.name}" for frame in reversed(frames)]
)
return "\n".join(
[f"{frame['filename']}:{frame['line']} {frame['name']}" for frame in reversed(frames)]
)
return "\n".join(_format_frame(frame) for frame in reversed(frames))


def _validate_raw_frames(frames: list[dict]) -> None:
def _validate_raw_frames(frames: list[dict[str, Any]]) -> None:
for frame in frames:
_ = frame["filename"]
_ = frame["line"]
Expand Down Expand Up @@ -76,12 +76,12 @@ class TraceEntry:
device_free: int = -1 # only present for OOM, the amount of
# memory npu still reports to be free

_origin: dict = None # Readonly
idx: int = -1 # 索引,全局唯一
_raw_frames: list[dict] | None = field(default=None, repr=False)
_origin: dict[str, Any] | None = None # Readonly
idx: int | None = -1 # 索引,全局唯一
_raw_frames: list[dict[str, Any]] | None = field(default=None, repr=False)

@classmethod
def from_dict(cls, trace_dict: dict, _raw_frames: bool = False):
def from_dict(cls, trace_dict: dict[str, Any], _raw_frames: bool = False):
frame_dicts = trace_dict.get("frames", [])
if _raw_frames:
_validate_raw_frames(frame_dicts)
Expand All @@ -98,7 +98,7 @@ def from_dict(cls, trace_dict: dict, _raw_frames: bool = False):
)
return trace_entry

def callstack_frames(self) -> list[Frame] | list[dict]:
def callstack_frames(self) -> list[Frame] | list[dict[str, Any]]:
"""Return the frame container that backs ``get_callstack()``.

Callers that deduplicate callstacks key on this container's identity,
Expand All @@ -112,7 +112,7 @@ def get_callstack(self):
def to_dict(self, include_id: bool = False):
if self._origin and not include_id:
return self._origin
trace_dict = (
trace_dict: dict[str, Any] = (
dict(self._origin)
if self._origin
else {
Expand Down Expand Up @@ -157,12 +157,12 @@ class Block:

# 指向持有该block的segment对象
segment_ptr: Any = None
free_event_idx: int = None
alloc_event_idx: int = None
_raw_frames: list[dict] | None = field(default=None, repr=False)
free_event_idx: int | None = None
alloc_event_idx: int | None = None
_raw_frames: list[dict[str, Any]] | None = field(default=None, repr=False)

@classmethod
def from_dict(cls, block_dict: dict, _raw_frames: bool = False):
def from_dict(cls, block_dict: dict[str, Any], _raw_frames: bool = False):
frame_dicts = block_dict.get("frames", [])
if _raw_frames:
_validate_raw_frames(frame_dicts)
Expand Down Expand Up @@ -212,21 +212,24 @@ class Segment:
address: int = -1
total_size: int = 0 # aclrtMalloc'd size of segment
stream: int = 0
segment_type: Literal["small", "large"] = "" # 'large' (>1MB)
segment_type: Literal["small", "large", ""] = "" # 'large' (>1MB)
allocated_size: int = 0 # size of memory in use
active_size: int = 0 # size of memory in use or in active_awaiting_free state
blocks: list[Block] = field(default_factory=list)
device: int = 0
frames: list[Frame] = field(default_factory=list)
is_expandable: bool = False
_origin: dict = None # Readonly
free_or_unmap_event_idx: int = None
alloc_or_map_event_idx: int = None
_raw_frames: list[dict] | None = field(default=None, repr=False)
_origin: dict[str, Any] | None = None # Readonly
free_or_unmap_event_idx: int | None = None
alloc_or_map_event_idx: int | None = None
_raw_frames: list[dict[str, Any]] | None = field(default=None, repr=False)

@classmethod
def from_dict(
cls, segment_dict: dict, ignore_inactive_blocks: bool = False, _raw_frames: bool = False
cls,
segment_dict: dict[str, Any],
ignore_inactive_blocks: bool = False,
_raw_frames: bool = False,
):
frame_dicts = segment_dict.get("frames", [])
if _raw_frames:
Expand Down Expand Up @@ -260,7 +263,7 @@ def build_from_event(cls, event: TraceEntry, with_inactive_block: bool = False):
stream=event.stream,
frames=event.frames,
_raw_frames=event._raw_frames,
device=event.device if hasattr(event, "device") else 0,
device=cast(int, getattr(event, "device", 0)),
allocated_size=0,
active_size=0,
is_expandable=event.action in ["segment_map", "segment_unmap"],
Expand Down Expand Up @@ -309,10 +312,18 @@ class DeviceSnapshot:

device: int

def __init__(self) -> None:
self.segments = []
self.trace_entries = []
self.total_allocated = 0
self.total_reserved = 0
self.total_activated = 0
self.device = 0

@classmethod
def from_dict(
cls,
snapshot_dict: dict,
snapshot_dict: dict[str, Any],
device: int,
ignore_inactive_blocks: bool = False,
_raw_frames: bool = False,
Expand Down
2 changes: 1 addition & 1 deletion src/pt_snap_cli/snapshot/simulate/allocator_context.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
class AllocatorContext:
def __init__(self, snapshot: DeviceSnapshot):
self.device_snapshot = snapshot
self.current_undo_event: TraceEntry = None
self.current_undo_event: TraceEntry | None = None
self.workspace_flag = False

def set_current_undo_event(self, undo_event: TraceEntry):
Expand Down
11 changes: 7 additions & 4 deletions src/pt_snap_cli/snapshot/simulate/simulate.py
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
from logging import Logger
from typing import Any

from ..base import Block, BlockState, DeviceSnapshot
from ..util import get_logger
from . import snapshot_lookup, snapshot_mutator
from .allocator_context import AllocatorContext
from .hooker_defs import AllocatorHooker, SimulateHooker
from .replay_executor import ReplayExecutor
from .simulated_caching_allocator import SimulatedCachingAllocator
from .snapshot_lookup import find_segment
from .snapshot_mutator import attach_block

loading_logger = get_logger("LOAD")
replay_logger = get_logger("REPLAY")
Expand All @@ -20,12 +22,13 @@ class SimulateDeviceSnapshot:
_loading_logger: Logger
_replay_logger: Logger

def __init__(self, snapshot_dict: dict, device: int, *, _raw_frames: bool = False):
def __init__(self, snapshot_dict: dict[str, Any], device: int, *, _raw_frames: bool = False):
# 基于device初始化logger
self._loading_logger = loading_logger.getChild(f"{device}")
self._replay_logger = replay_logger.getChild(f"{device}")
if not snapshot_dict:
raise RuntimeError("Cannot init snapshot from empty data.")
self.device = device
self._loading_logger.info("Loading snapshot data...")
self.device_snapshot = DeviceSnapshot.from_dict(
snapshot_dict,
Expand Down Expand Up @@ -89,7 +92,7 @@ def _adapt_workspace_snapshot(self):
f"(stream {workspace_snapshot.stream}) is internally inconsistent"
)
break
_, existed_seg = snapshot_lookup.find_segment(
_, existed_seg = find_segment(
snapshot, workspace_snapshot.addr, workspace_snapshot.stream
)
if existed_seg is None:
Expand Down Expand Up @@ -118,7 +121,7 @@ def _adapt_workspace_snapshot(self):
existed_seg.allocated_size = 0
existed_seg.active_size = 0
existed_seg.blocks = []
snapshot_mutator.attach_block(
attach_block(
snapshot,
existed_seg,
Block(
Expand Down
Loading
Loading