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
20 changes: 19 additions & 1 deletion src/pt_snap_cli/api.py
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
ImportMetadataService,
QueryService,
)
from pt_snap_cli.core.context_cache import ContextCache


@dataclass
Expand All @@ -34,14 +35,31 @@ def __init__(
self,
db_path: Path | None = None,
device_id: int | None = None,
*,
context_cache: ContextCache | None = None,
) -> None:
self._config = Config()
self._db_path = db_path
self._device_id = device_id
self._focus_service = FocusService(self._config)
self._query_service = QueryService(self._focus_service)
# Share one context cache across the analyzer so that long-lived
# analyzers (e.g. the MCP server singleton) reuse a single
# SQLite connection and skip schema validation on every query.
# Explicit ``is not None`` because an empty cache is falsy via
# ``__len__`` and would be silently replaced otherwise.
self._context_cache = context_cache if context_cache is not None else ContextCache()
self._query_service = QueryService(self._focus_service, context_cache=self._context_cache)
self._metadata_service = ImportMetadataService()

@property
def context_cache(self) -> ContextCache:
"""Return the :class:`ContextCache` this analyzer uses."""
return self._context_cache

def invalidate_context_cache(self, db_path: Path | str | None = None) -> None:
"""Drop a cached context (or every cached context when ``db_path`` is None)."""
self._context_cache.invalidate(db_path)

def get_focus(self) -> FocusState:
state = self._focus_service.get_focus(
explicit_db_path=self._db_path,
Expand Down
52 changes: 40 additions & 12 deletions src/pt_snap_cli/context.py
Original file line number Diff line number Diff line change
Expand Up @@ -25,22 +25,40 @@ class Context:
"""Database context manager for PyTorch memory snapshot analysis.

Manages SQLite database connections in read-only mode with schema validation.

By default the underlying SQLite connection is opened and closed for every
``connect()`` context. Pass ``persistent=True`` to keep the connection
alive across calls so that long-lived owners (e.g. a ``ContextCache``
shared by an MCP server) can avoid the per-query open/close cost.
Persistent contexts still close their connection when ``close()`` is
invoked explicitly.
"""

def __init__(self, db_path: str | Path, devices: list[int] | None = None):
def __init__(
self,
db_path: str | Path,
devices: list[int] | None = None,
*,
persistent: bool = False,
):
"""Initialize context with database path.

Args:
db_path: Path to the SQLite database file.
devices: Optional list of device IDs to filter.
persistent: When True, the connection stays open after each
``connect()`` call so it can be reused. The caller is
responsible for invoking ``close()`` to release it.

Raises:
DatabaseNotFoundError: If database file does not exist.
SchemaVersionError: If database schema is invalid.
"""
self.db_path = Path(db_path)
self._devices = devices
self._persistent = persistent
self._conn: sqlite3.Connection | None = None
self._connect_depth = 0
self._device_ids: list[int] | None = None

if not self.db_path.exists():
Expand Down Expand Up @@ -108,27 +126,37 @@ def cursor(self) -> sqlite3.Cursor:
def connect(self) -> Generator[sqlite3.Connection, None, None]:
"""Context manager for database connection.

Opens database in read-only mode for safe analysis.
Opens database in read-only mode for safe analysis. When the
context was constructed with ``persistent=True`` the underlying
SQLite connection remains open after the context exits and is
reused by subsequent ``connect()`` calls until ``close()`` is
invoked explicitly.

Yields:
SQLite connection object.
"""
if self._conn is not None:
yield self._conn
return
if self._conn is None:
# Keep the colon in Windows drive prefixes while encoding SQLite URI metacharacters.
encoded_path = quote(self.db_path.as_posix(), safe="/:")
uri = f"file:{encoded_path}?mode=ro"
self._conn = sqlite3.connect(uri, uri=True)
self._conn.row_factory = sqlite3.Row

# Keep the colon in Windows drive prefixes while encoding SQLite URI metacharacters.
encoded_path = quote(self.db_path.as_posix(), safe="/:")
uri = f"file:{encoded_path}?mode=ro"
self._conn = sqlite3.connect(uri, uri=True)
self._conn.row_factory = sqlite3.Row
self._connect_depth += 1
try:
yield self._conn
finally:
self.close()
if self._connect_depth > 0:
self._connect_depth -= 1
if not self._persistent and self._connect_depth == 0:
self.close()

def close(self) -> None:
"""Close the database connection."""
"""Close the database connection.

Safe to call multiple times and on already-closed contexts.
"""
if self._conn is not None:
self._conn.close()
self._conn = None
self._connect_depth = 0
121 changes: 121 additions & 0 deletions src/pt_snap_cli/core/context_cache.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
"""LRU cache for read-only SQLite ``Context`` instances.

The cache exists so that long-lived owners (e.g. the MCP server, which keeps
a single :class:`SnapshotAnalyzer` alive across many tool calls) can reuse a
single :class:`pt_snap_cli.context.Context` -- and its persistent read-only
SQLite connection -- instead of paying the cost of ``dictionary`` schema
validation, device discovery, and a fresh ``sqlite3.connect`` URI handshake on
every query.

Entries are keyed by the resolved absolute path of the database file and
stamped with a file signature at the time of insertion. On lookup the cache
compares the current signature to the cached value and evicts the entry on
mismatch, so a database that is replaced on disk (for example, by
``pt-snap import``) is re-opened automatically even when the replacement has
the same mtime. Callers can also force a refresh with
:meth:`ContextCache.invalidate`.
"""

from __future__ import annotations

import sqlite3
from collections import OrderedDict
from pathlib import Path
from typing import TYPE_CHECKING

from pt_snap_cli.context import Context, DatabaseNotFoundError

if TYPE_CHECKING:
pass

FileSignature = tuple[int, int, int]


class ContextCache:
"""LRU cache of :class:`Context` instances keyed by absolute db path."""

def __init__(self, maxsize: int = 4) -> None:
if maxsize <= 0:
raise ValueError("maxsize must be positive")
self._maxsize = maxsize
# Insertion order doubles as LRU recency (oldest first).
self._entries: OrderedDict[Path, tuple[Context, FileSignature]] = OrderedDict()

@property
def maxsize(self) -> int:
return self._maxsize

def __len__(self) -> int:
return len(self._entries)

def get(self, db_path: Path | str) -> Context:
"""Return a cached or freshly opened :class:`Context` for ``db_path``.

On a hit the cached entry is promoted to most-recently-used. On a
miss -- or when the file's signature has changed -- a new persistent
context is created and stored, evicting the oldest entry once the
cache is full.

Raises:
DatabaseNotFoundError: If ``db_path`` does not exist on disk.
"""
key = Path(db_path).expanduser().resolve()
if not key.exists():
raise DatabaseNotFoundError(f"Database not found: {key}")

# Probe metadata first so a missing/inaccessible file raises
# consistently whether the cache is hit or missed.
current_signature = self._file_signature(key)

cached = self._entries.get(key)
if cached is not None:
ctx, cached_signature = cached
if cached_signature == current_signature:
self._entries.move_to_end(key)
return ctx
self._safe_close(ctx)
del self._entries[key]

ctx = Context(key, persistent=True)
self._entries[key] = (ctx, current_signature)
self._evict_if_needed()
return ctx

def invalidate(self, db_path: Path | str | None = None) -> None:
"""Drop a single cached entry or every entry when ``db_path`` is None."""
if db_path is None:
while self._entries:
_, (ctx, _) = self._entries.popitem(last=False)
self._safe_close(ctx)
return
key = Path(db_path).expanduser().resolve()
cached = self._entries.pop(key, None)
if cached is not None:
self._safe_close(cached[0])

def close(self) -> None:
"""Drop every cached entry and close the underlying connections."""
self.invalidate()

def _evict_if_needed(self) -> None:
while len(self._entries) > self._maxsize:
_, (ctx, _) = self._entries.popitem(last=False)
self._safe_close(ctx)

@staticmethod
def _safe_close(ctx: Context) -> None:
try:
ctx.close()
except sqlite3.Error:
# Already-closed connections are fine; other sqlite errors are
# best-effort cleanup, never worth masking the real exception.
pass

@staticmethod
def _file_signature(path: Path) -> FileSignature:
"""Return metadata that changes when a database is replaced in place."""
stat = path.stat()
return (stat.st_mtime_ns, stat.st_ino, stat.st_size)


__all__ = ["ContextCache"]
57 changes: 43 additions & 14 deletions src/pt_snap_cli/core/query_service.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
from typing import Any

from pt_snap_cli.context import Context, DatabaseNotFoundError, SchemaVersionError
from pt_snap_cli.core.context_cache import ContextCache
from pt_snap_cli.core.errors import (
DatabaseMissingError,
DatabaseSchemaError,
Expand All @@ -30,8 +31,29 @@


class QueryService:
def __init__(self, focus_service: FocusService | None = None) -> None:
def __init__(
self,
focus_service: FocusService | None = None,
*,
context_cache: ContextCache | None = None,
) -> None:
self._focus_service = focus_service or FocusService()
# Cache Context instances across calls so long-lived owners (MCP
# server, SnapshotAnalyzer) skip the per-call schema validation and
# SQLite connect/close handshake. See ContextCache for the LRU and
# mtime invalidation semantics.
self._context_cache = context_cache if context_cache is not None else ContextCache()
self._executor: QueryExecutor | None = None
self._executor_context: Context | None = None

@property
def context_cache(self) -> ContextCache:
"""Return the :class:`ContextCache` backing this service."""
return self._context_cache

def invalidate_context_cache(self, db_path: Path | str | None = None) -> None:
"""Drop a cached context (or all of them when ``db_path`` is None)."""
self._context_cache.invalidate(db_path)

def list_templates(
self,
Expand Down Expand Up @@ -112,31 +134,38 @@ def execute_query(

ctx = self._validated_context(resolved.db_path)
target_device = self._resolve_device_id(ctx, resolved.device_id, device_id)
executor = QueryExecutor(
ctx, template_dir=Path(__file__).parent.parent / "query" / "templates"
)
executor = self._get_executor(ctx)

try:
rows = executor.execute_template(template, params or {}, device_id=target_device)
rows = executor.execute_template(
template, params or {}, device_id=target_device, max_rows=max_rows
)
total = len(rows)
if max_rows is not None and max_rows > 0 and len(rows) == max_rows:
total = executor.count_template(template, params or {}, device_id=target_device)
except ExecutorTemplateRenderError as exc:
raise TemplateRenderError(str(exc)) from exc
except ExecutorQueryExecutionError as exc:
if get_query(template) is None:
raise TemplateNotFoundError(f"Template '{template}' not found") from exc
raise QueryExecutionError(str(exc)) from exc

if max_rows is None or max_rows <= 0:
limited_rows = rows
else:
limited_rows = rows[:max_rows]

return QueryResult(
total=len(rows),
returned=len(limited_rows),
total=total,
returned=len(rows),
device_id=target_device,
rows=limited_rows,
rows=rows,
)

def _get_executor(self, ctx: Context) -> QueryExecutor:
"""Reuse the executor while its cached database context remains valid."""
if self._executor is None or self._executor_context is not ctx:
self._executor = QueryExecutor(
ctx, template_dir=Path(__file__).parent.parent / "query" / "templates"
)
self._executor_context = ctx
return self._executor

def _resolve_device_id(
self,
ctx: Context,
Expand All @@ -163,7 +192,7 @@ def _resolve_device_id(

def _validated_context(self, db_path: Path) -> Context:
try:
return Context(db_path)
return self._context_cache.get(db_path)
except DatabaseNotFoundError as exc:
raise DatabaseMissingError(str(exc)) from exc
except (SchemaVersionError, sqlite3.DatabaseError) as exc:
Expand Down
Loading
Loading