libcontext 0.3.0__tar.gz → 0.5.0__tar.gz

{libcontext-0.3.0 → libcontext-0.5.0}/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-03-23
+
+### Added
+
+- **`--version` flag**: `libctx --version` displays the installed version, read from package metadata.
+- **`cache list`**: new subcommand showing cached packages with version, size, and relative age.
+- **`cache clear <package>`**: selective cache clearing by package name (normalises hyphens and case). Without argument, `cache clear` still removes all entries as before.
+
+## [0.4.0] - 2026-03-23
+
+### Added
+
+- **Auto-detect project venv**: libcontext now automatically detects `.venv/` or `venv/` in the current directory and uses it for package discovery. This fixes the core issue where `uv tool install libcontext` could not see packages from project environments.
+- **`--python` CLI option**: explicit override for targeting a specific Python interpreter or venv directory (e.g. `--python /path/to/other/venv`).
+- **`LIBCONTEXT_PYTHON` env var**: configure the MCP server's target environment via environment variable or `--python` argument.
+- **`EnvironmentSetupError` exception**: raised when a target environment cannot be resolved or queried.
+- **Cache namespacing by environment**: packages from different environments get separate cache entries, preventing cross-environment cache collisions.
+
 ## [0.3.0] - 2026-03-23
 
 ### Added
@@ -83,7 +101,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Free-form `extra_context` field for library authors.
 - Python API for programmatic usage (`collect_package`, `render_package`).
 
-[Unreleased]: https://github.com/Syclaw/libcontext/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/Syclaw/libcontext/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/Syclaw/libcontext/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/Syclaw/libcontext/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/Syclaw/libcontext/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/Syclaw/libcontext/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/Syclaw/libcontext/releases/tag/v0.1.0

{libcontext-0.3.0 → libcontext-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: libcontext
-Version: 0.3.0
+Version: 0.5.0
 Summary: Generate optimized LLM context from Python library APIs — CLI, skill, and MCP server
 Project-URL: Homepage, https://github.com/Syclaw/libcontext
 Project-URL: Repository, https://github.com/Syclaw/libcontext
@@ -37,30 +37,38 @@ Description-Content-Type: text/markdown
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![Typed](https://img.shields.io/badge/typed-mypy-blue.svg)](https://mypy-lang.org/)
 
-> Make your AI coding assistant aware of any Python library's API — on demand, not always-on.
+> Context-efficient API references for LLM toolchains — structured, on-demand, not always-on.
 
 **libcontext** inspects any installed Python package via static AST analysis (no code execution) and generates compact Markdown API references. It integrates with Claude Code (via a `/lib` skill) and VS Code Copilot (via an MCP server) to provide **progressive disclosure** — only loading API context when you actually need it, avoiding context window pollution.
 
 ## Why This Exists
 
-When you ask an AI assistant how to use a library, the quality of the output depends entirely on what the model knows about that library's API. For many real-world scenarios, the model is working blind:
+LLMs can often use popular libraries correctly from training data alone. For well-known packages like `requests` or `flask`, libcontext adds little value. The real problems arise in specific scenarios:
 
 - **Internal / private libraries** — Zero training data exists. The model has never seen the API.
-- **Niche open-source packages** — Sparse or outdated training data leads to hallucinated methods and wrong signatures.
+- **Niche open-source packages** — Sparse or outdated training data leads to hallucinated methods and wrong signatures. GPT-4o achieves only 38% valid invocations on low-frequency APIs ([Amazon Science, ICSE 2025](https://www.amazon.science/publications/on-mitigating-code-llm-hallucinations-with-api-documentation)).
 - **New versions of any library** — Training data has a cutoff. The model knows v2, you're using v3.
 
-Dumping entire API references into always-on instruction files (like `copilot-instructions.md` or `CLAUDE.md`) wastes context window on every interaction — even when you're not using that library. Research ([ReadMe.LLM, UC Berkeley 2025](https://arxiv.org/abs/2504.15870)) confirms that excessive context triggers hallucinations and degrades output quality.
+Even when an LLM could read source files directly, structured API summaries are more context-efficient: providing API documentation via retrieval improves pass rates by 83–220% compared to no documentation, while consuming far fewer tokens than raw source code ([arXiv 2503.15231, March 2025](https://arxiv.org/abs/2503.15231)).
 
-libcontext solves this with **progressive disclosure**: overview first, then drill into specific modules only when needed.
+Dumping entire API references into always-on instruction files wastes context window on every interaction. Selective retrieval outperforms always-on injection — always-on docs actually hurt performance on well-known APIs ([Amazon Science, ICSE 2025](https://www.amazon.science/publications/on-mitigating-code-llm-hallucinations-with-api-documentation)).
+
+libcontext addresses this with **progressive disclosure**: overview first, then drill into specific modules only when needed.
 
 ## When libcontext makes the biggest difference
 
 | Scenario | Impact | Why |
 |---|---|---|
-| **Internal / private libraries** | Critical | Zero training data exists for proprietary code |
-| **Niche open-source packages** | High | Sparse training data leads to hallucinated methods |
+| **Internal / private libraries** | Critical | Zero training data — the model has never seen the API |
+| **Niche open-source packages** | High | Sparse training data; 19.7% of LLM package suggestions are hallucinated ([USENIX Security 2025](https://www.usenix.org/publications/loginonline/we-have-package-you-comprehensive-analysis-package-hallucinations-code)) |
 | **New versions of any library** | High | Training cutoff — the LLM knows v2, you're using v3 |
-| **Popular, stable libraries** | Low | The LLM already has good knowledge from training data |
+| **Popular, stable libraries** | Low | The LLM already has good knowledge from training data — libcontext adds little here |
+
+### What libcontext does NOT do
+
+- **Replace reading source code** — LLMs with tool access (Claude Code, Cursor) can read files directly. For popular libraries, that's often sufficient.
+- **Guarantee correctness** — Even with perfect API docs, LLMs still make errors. Research shows pass rates of 74–91% with target documentation, not 100% ([arXiv 2503.15231](https://arxiv.org/abs/2503.15231)).
+- **Provide usage examples** — libcontext extracts signatures and docstrings, not example code. Research indicates examples have the highest impact on code generation quality.
 
 ## Quick Start
 
@@ -138,8 +146,10 @@ libctx diff old.json new.json
 # Bypass disk cache
 libctx inspect requests --no-cache
 
-# Clear all cached API data
-libctx cache clear
+# Cache management
+libctx cache list               # show cached packages with size and age
+libctx cache clear               # clear all cached API data
+libctx cache clear requests      # clear only the entries for one package
 ```
 
 ### AST Analysis

{libcontext-0.3.0 → libcontext-0.5.0}/README.md

@@ -8,30 +8,38 @@
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![Typed](https://img.shields.io/badge/typed-mypy-blue.svg)](https://mypy-lang.org/)
 
-> Make your AI coding assistant aware of any Python library's API — on demand, not always-on.
+> Context-efficient API references for LLM toolchains — structured, on-demand, not always-on.
 
 **libcontext** inspects any installed Python package via static AST analysis (no code execution) and generates compact Markdown API references. It integrates with Claude Code (via a `/lib` skill) and VS Code Copilot (via an MCP server) to provide **progressive disclosure** — only loading API context when you actually need it, avoiding context window pollution.
 
 ## Why This Exists
 
-When you ask an AI assistant how to use a library, the quality of the output depends entirely on what the model knows about that library's API. For many real-world scenarios, the model is working blind:
+LLMs can often use popular libraries correctly from training data alone. For well-known packages like `requests` or `flask`, libcontext adds little value. The real problems arise in specific scenarios:
 
 - **Internal / private libraries** — Zero training data exists. The model has never seen the API.
-- **Niche open-source packages** — Sparse or outdated training data leads to hallucinated methods and wrong signatures.
+- **Niche open-source packages** — Sparse or outdated training data leads to hallucinated methods and wrong signatures. GPT-4o achieves only 38% valid invocations on low-frequency APIs ([Amazon Science, ICSE 2025](https://www.amazon.science/publications/on-mitigating-code-llm-hallucinations-with-api-documentation)).
 - **New versions of any library** — Training data has a cutoff. The model knows v2, you're using v3.
 
-Dumping entire API references into always-on instruction files (like `copilot-instructions.md` or `CLAUDE.md`) wastes context window on every interaction — even when you're not using that library. Research ([ReadMe.LLM, UC Berkeley 2025](https://arxiv.org/abs/2504.15870)) confirms that excessive context triggers hallucinations and degrades output quality.
+Even when an LLM could read source files directly, structured API summaries are more context-efficient: providing API documentation via retrieval improves pass rates by 83–220% compared to no documentation, while consuming far fewer tokens than raw source code ([arXiv 2503.15231, March 2025](https://arxiv.org/abs/2503.15231)).
 
-libcontext solves this with **progressive disclosure**: overview first, then drill into specific modules only when needed.
+Dumping entire API references into always-on instruction files wastes context window on every interaction. Selective retrieval outperforms always-on injection — always-on docs actually hurt performance on well-known APIs ([Amazon Science, ICSE 2025](https://www.amazon.science/publications/on-mitigating-code-llm-hallucinations-with-api-documentation)).
+
+libcontext addresses this with **progressive disclosure**: overview first, then drill into specific modules only when needed.
 
 ## When libcontext makes the biggest difference
 
 | Scenario | Impact | Why |
 |---|---|---|
-| **Internal / private libraries** | Critical | Zero training data exists for proprietary code |
-| **Niche open-source packages** | High | Sparse training data leads to hallucinated methods |
+| **Internal / private libraries** | Critical | Zero training data — the model has never seen the API |
+| **Niche open-source packages** | High | Sparse training data; 19.7% of LLM package suggestions are hallucinated ([USENIX Security 2025](https://www.usenix.org/publications/loginonline/we-have-package-you-comprehensive-analysis-package-hallucinations-code)) |
 | **New versions of any library** | High | Training cutoff — the LLM knows v2, you're using v3 |
-| **Popular, stable libraries** | Low | The LLM already has good knowledge from training data |
+| **Popular, stable libraries** | Low | The LLM already has good knowledge from training data — libcontext adds little here |
+
+### What libcontext does NOT do
+
+- **Replace reading source code** — LLMs with tool access (Claude Code, Cursor) can read files directly. For popular libraries, that's often sufficient.
+- **Guarantee correctness** — Even with perfect API docs, LLMs still make errors. Research shows pass rates of 74–91% with target documentation, not 100% ([arXiv 2503.15231](https://arxiv.org/abs/2503.15231)).
+- **Provide usage examples** — libcontext extracts signatures and docstrings, not example code. Research indicates examples have the highest impact on code generation quality.
 
 ## Quick Start
 
@@ -109,8 +117,10 @@ libctx diff old.json new.json
 # Bypass disk cache
 libctx inspect requests --no-cache
 
-# Clear all cached API data
-libctx cache clear
+# Cache management
+libctx cache list               # show cached packages with size and age
+libctx cache clear               # clear all cached API data
+libctx cache clear requests      # clear only the entries for one package
 ```
 
 ### AST Analysis

{libcontext-0.3.0 → libcontext-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "libcontext"
-version = "0.3.0"
+version = "0.5.0"
 description = "Generate optimized LLM context from Python library APIs — CLI, skill, and MCP server"
 readme = "README.md"
 license = "MIT"

{libcontext-0.3.0 → libcontext-0.5.0}/src/libcontext/__init__.py

@@ -27,6 +27,7 @@ from .config import LibcontextConfig
 from .diff import diff_packages
 from .exceptions import (
     ConfigError,
+    EnvironmentSetupError,
     InspectionError,
     LibcontextError,
     PackageNotFoundError,
@@ -69,6 +70,7 @@ __all__ = [
     "ClassInfo",
     "ConfigError",
     "DiffResult",
+    "EnvironmentSetupError",
     "FunctionDiff",
     "FunctionInfo",
     "InspectionError",

libcontext-0.5.0/src/libcontext/_envsetup.py

@@ -0,0 +1,334 @@
+"""Environment setup — resolve and activate a target Python environment.
+
+When libcontext is installed globally (e.g. via ``uv tool install``), it
+runs inside its own isolated venv and cannot see packages from a project's
+``.venv``.  This module auto-detects a project venv in the current working
+directory, or accepts an explicit ``--python`` override, and injects the
+target environment's paths into ``sys.path`` so that :mod:`importlib`
+discovery works against the target environment.
+
+Detection priority:
+1. Explicit ``--python`` argument → use that environment.
+2. ``.venv/`` or ``venv/`` in CWD → use the detected venv.
+3. Neither → use the current process's environment (no injection).
+"""
+
+from __future__ import annotations
+
+import importlib
+import json
+import logging
+import subprocess
+import sys
+from collections.abc import Generator
+from contextlib import contextmanager
+from pathlib import Path
+
+from .exceptions import EnvironmentSetupError
+
+logger = logging.getLogger(__name__)
+
+_SUBPROCESS_TIMEOUT_SECONDS = 10
+
+
+_VENV_DIR_NAMES = (".venv", "venv")
+
+
+def auto_detect_venv(cwd: Path | None = None) -> Path | None:
+    """Detect a project venv in the current working directory.
+
+    Checks for ``.venv/`` then ``venv/`` in *cwd* (defaults to
+    ``Path.cwd()``).  Only considers directories that contain a
+    recognisable Python interpreter.
+
+    Args:
+        cwd: Directory to search in.  Defaults to the process CWD.
+
+    Returns:
+        Path to the venv directory, or *None* if no venv is found.
+    """
+    if cwd is None:
+        cwd = Path.cwd()
+
+    for name in _VENV_DIR_NAMES:
+        candidate = cwd / name
+        if not candidate.is_dir():
+            continue
+        # Verify it actually contains an interpreter
+        interpreters = [
+            candidate / "Scripts" / "python.exe",
+            candidate / "bin" / "python",
+            candidate / "bin" / "python3",
+        ]
+        if any(exe.is_file() for exe in interpreters):
+            logger.debug("Auto-detected venv at '%s'", candidate)
+            return candidate
+
+    return None
+
+
+def setup_environment(
+    python_arg: str | None = None,
+    *,
+    cwd: Path | None = None,
+) -> str | None:
+    """Set up the target environment for package discovery.
+
+    Implements the detection priority:
+    1. Explicit *python_arg* → inject that environment.
+    2. Auto-detected venv in *cwd* → inject it.
+    3. Neither → no injection (current process environment).
+
+    Args:
+        python_arg: Explicit ``--python`` value, or *None*.
+        cwd: Working directory for auto-detection (defaults to CWD).
+
+    Returns:
+        The env_tag for cache namespacing, or *None* if no injection
+        was performed.
+
+    Raises:
+        EnvironmentSetupError: If an explicit *python_arg* is invalid.
+    """
+    target: str | None = python_arg
+
+    if target is None:
+        detected = auto_detect_venv(cwd)
+        if detected is not None:
+            target = str(detected)
+
+    if target is None:
+        return None
+
+    # Resolve once, reuse for both injection and tag computation
+    python_exe = resolve_python_executable(target)
+    target_paths = get_target_sys_path(python_exe)
+
+    current_set = set(sys.path)
+    new_paths = [p for p in target_paths if p and p not in current_set]
+
+    sys.path[:0] = new_paths
+    importlib.invalidate_caches()
+
+    logger.debug(
+        "Activated environment '%s': injected %d paths",
+        target,
+        len(new_paths),
+    )
+
+    return _env_tag_from_resolved(python_exe)
+
+
+def resolve_python_executable(python_arg: str) -> Path:
+    """Resolve a user-supplied path to a Python executable.
+
+    Accepts either a direct path to a Python interpreter or a venv
+    directory.  When given a directory, probes for the interpreter
+    in the standard locations (``Scripts/python.exe`` on Windows,
+    ``bin/python`` on Unix).
+
+    Args:
+        python_arg: Path to a Python interpreter or venv directory.
+
+    Returns:
+        Resolved absolute path to the Python executable.
+
+    Raises:
+        EnvironmentSetupError: If the path does not exist or no
+            interpreter can be found.
+    """
+    path = Path(python_arg)
+
+    if not path.exists():
+        raise EnvironmentSetupError(
+            python_arg,
+            f"path does not exist: {python_arg}",
+        )
+
+    # Direct path to an executable
+    if path.is_file():
+        return path.resolve()
+
+    # Directory — probe for interpreter
+    if path.is_dir():
+        candidates = [
+            path / "Scripts" / "python.exe",  # Windows venv
+            path / "bin" / "python",  # Unix venv
+            path / "bin" / "python3",  # Unix alternative
+        ]
+        for candidate in candidates:
+            if candidate.is_file():
+                logger.debug(
+                    "Resolved venv directory '%s' to interpreter '%s'",
+                    python_arg,
+                    candidate,
+                )
+                return candidate.resolve()
+
+        raise EnvironmentSetupError(
+            python_arg,
+            f"no Python interpreter found in directory: {python_arg}. "
+            f"Expected Scripts/python.exe (Windows) or bin/python (Unix).",
+        )
+
+    raise EnvironmentSetupError(
+        python_arg,
+        f"path is neither a file nor a directory: {python_arg}",
+    )
+
+
+def get_target_sys_path(python_exe: Path) -> list[str]:
+    """Query a Python interpreter for its ``sys.path``.
+
+    Runs the interpreter in a subprocess with a short timeout to
+    extract the full search path, including ``.pth`` expansions and
+    site-packages.
+
+    Args:
+        python_exe: Absolute path to the target Python executable.
+
+    Returns:
+        List of path strings from the target interpreter's ``sys.path``.
+
+    Raises:
+        EnvironmentSetupError: If the subprocess fails or times out.
+    """
+    script = "import sys, json; print(json.dumps(sys.path))"
+    try:
+        result = subprocess.run(
+            [str(python_exe), "-c", script],
+            capture_output=True,
+            text=True,
+            timeout=_SUBPROCESS_TIMEOUT_SECONDS,
+        )
+    except (FileNotFoundError, OSError) as exc:
+        raise EnvironmentSetupError(
+            str(python_exe),
+            f"cannot execute interpreter: {exc}",
+        ) from exc
+    except subprocess.TimeoutExpired as exc:
+        raise EnvironmentSetupError(
+            str(python_exe),
+            f"interpreter timed out after {_SUBPROCESS_TIMEOUT_SECONDS}s",
+        ) from exc
+
+    if result.returncode != 0:
+        stderr = result.stderr.strip()[:200]
+        raise EnvironmentSetupError(
+            str(python_exe),
+            f"interpreter exited with code {result.returncode}: {stderr}",
+        )
+
+    try:
+        paths = json.loads(result.stdout)
+    except json.JSONDecodeError as exc:
+        raise EnvironmentSetupError(
+            str(python_exe),
+            f"cannot parse sys.path output: {exc}",
+        ) from exc
+
+    if not isinstance(paths, list):
+        raise EnvironmentSetupError(
+            str(python_exe),
+            "sys.path output is not a list",
+        )
+
+    return [str(p) for p in paths]
+
+
+@contextmanager
+def activate_environment(python_arg: str) -> Generator[Path, None, None]:
+    """Temporarily inject a target environment's paths into the process.
+
+    Resolves the Python executable, queries its ``sys.path``, prepends
+    the target paths to the current ``sys.path``, and invalidates
+    :mod:`importlib` caches so that :func:`importlib.util.find_spec`
+    and :func:`importlib.metadata.distributions` pick up the target
+    environment's packages.
+
+    The original ``sys.path`` is restored on exit.
+
+    Args:
+        python_arg: Path to a Python interpreter or venv directory.
+
+    Yields:
+        The resolved Python executable path.
+
+    Raises:
+        EnvironmentSetupError: If the environment cannot be resolved
+            or queried.
+    """
+    python_exe = resolve_python_executable(python_arg)
+    target_paths = get_target_sys_path(python_exe)
+
+    # Filter to paths that actually exist and aren't already present
+    current_set = set(sys.path)
+    new_paths = [p for p in target_paths if p and p not in current_set]
+
+    saved_path = sys.path.copy()
+    try:
+        # Prepend target paths so they take priority
+        sys.path[:0] = new_paths
+        importlib.invalidate_caches()
+
+        logger.debug(
+            "Activated environment '%s': injected %d paths",
+            python_arg,
+            len(new_paths),
+        )
+        yield python_exe
+    finally:
+        sys.path[:] = saved_path
+        importlib.invalidate_caches()
+        logger.debug("Restored original sys.path")
+
+
+def inject_target_environment(python_arg: str) -> None:
+    """Inject a target environment's paths into the current process.
+
+    Unlike :func:`activate_environment`, this does **not** restore
+    ``sys.path`` afterward.  Suitable for CLI entry points where the
+    process exits after the command completes.
+
+    Args:
+        python_arg: Path to a Python interpreter or venv directory.
+
+    Raises:
+        EnvironmentSetupError: If the environment cannot be resolved
+            or queried.
+    """
+    python_exe = resolve_python_executable(python_arg)
+    target_paths = get_target_sys_path(python_exe)
+
+    current_set = set(sys.path)
+    new_paths = [p for p in target_paths if p and p not in current_set]
+
+    sys.path[:0] = new_paths
+    importlib.invalidate_caches()
+
+    logger.debug(
+        "Injected environment '%s': added %d paths",
+        python_arg,
+        len(new_paths),
+    )
+
+
+def _env_tag_from_resolved(python_exe: Path) -> str:
+    """Compute a short tag from an already-resolved interpreter path."""
+    import hashlib
+
+    digest = hashlib.sha256(str(python_exe).encode()).hexdigest()
+    return digest[:8]
+
+
+def env_tag_for_path(python_arg: str) -> str:
+    """Compute a short tag identifying a target environment for cache keys.
+
+    Args:
+        python_arg: The original ``--python`` argument (before resolution).
+
+    Returns:
+        An 8-character hex string derived from the resolved path.
+    """
+    resolved = resolve_python_executable(python_arg)
+    return _env_tag_from_resolved(resolved)

{libcontext-0.3.0 → libcontext-0.5.0}/src/libcontext/cache.py

@@ -113,6 +113,7 @@ def load(
     package_name: str,
     version: str | None,
     package_path: Path,
+    env_tag: str | None = None,
 ) -> PackageInfo | None:
     """Load a cached PackageInfo if still valid.
 
@@ -120,11 +121,12 @@ def load(
         package_name: Package name.
         version: Current installed version (from metadata).
         package_path: Path to the package source (for mtime check).
+        env_tag: Environment identifier (from ``--python``).
 
     Returns:
         Cached PackageInfo if valid, None on miss or invalidation.
     """
-    cache_file = _get_cache_dir() / _cache_filename(package_name, version)
+    cache_file = _get_cache_dir() / _cache_filename(package_name, version, env_tag)
 
     if not cache_file.is_file():
         logger.debug("Cache miss for %r: file not found", package_name)
@@ -178,6 +180,7 @@ def save(
     package_info: PackageInfo,
     package_path: Path,
     source_stats: _SourceStats | None = None,
+    env_tag: str | None = None,
 ) -> None:
     """Save a PackageInfo to the disk cache.
 
@@ -185,6 +188,7 @@ def save(
         package_info: The collected package data.
         package_path: Path to the package source (for mtime computation).
         source_stats: Pre-computed stats. If None, stats are computed fresh.
+        env_tag: Environment identifier (from ``--python``).
     """
     if source_stats is None:
         source_stats = _compute_source_stats(package_path)
@@ -198,7 +202,9 @@ def save(
     envelope = _serialize_envelope(data)
 
     cache_dir = _get_cache_dir()
-    cache_file = cache_dir / _cache_filename(package_info.name, package_info.version)
+    cache_file = cache_dir / _cache_filename(
+        package_info.name, package_info.version, env_tag
+    )
 
     try:
         cache_file.write_text(
@@ -252,14 +258,93 @@ def clear_all() -> int:
     return count
 
 
-def _cache_filename(package_name: str, version: str | None) -> str:
+def clear_package(package_name: str) -> int:
+    """Remove cached entries matching a package name.
+
+    Matches entries whose embedded ``name`` field equals *package_name*
+    (case-insensitive, normalised with hyphens → underscores).
+
+    Args:
+        package_name: Package name to clear.
+
+    Returns:
+        Number of entries removed.
+    """
+    target = package_name.lower().replace("-", "_")
+    cache_dir = _get_cache_dir()
+    count = 0
+    for f in cache_dir.glob("*.json"):
+        try:
+            raw = json.loads(f.read_text(encoding="utf-8"))
+            data = _deserialize_envelope(raw)
+        except (json.JSONDecodeError, ValueError, OSError):
+            continue
+        name = data.get("name", "")
+        if isinstance(name, str) and name.lower().replace("-", "_") == target:
+            _safe_delete(f)
+            count += 1
+    return count
+
+
+@dataclass
+class CacheEntry:
+    """Summary of a single cache entry for display."""
+
+    package: str
+    version: str
+    cached_at: str
+    size_bytes: int
+    file_path: Path
+
+
+def list_entries() -> list[CacheEntry]:
+    """List all cached API snapshots with metadata.
+
+    Returns:
+        List of :class:`CacheEntry` sorted by package name then version.
+    """
+    cache_dir = _get_cache_dir()
+    entries: list[CacheEntry] = []
+    for f in cache_dir.glob("*.json"):
+        try:
+            size = f.stat().st_size
+            raw = json.loads(f.read_text(encoding="utf-8"))
+            data = _deserialize_envelope(raw)
+        except (json.JSONDecodeError, ValueError, OSError):
+            continue
+        meta = data.get("_cache_meta", {})
+        entries.append(
+            CacheEntry(
+                package=data.get("name", "unknown"),
+                version=data.get("version", "unknown"),
+                cached_at=meta.get("cached_at", "unknown"),
+                size_bytes=size,
+                file_path=f,
+            )
+        )
+    entries.sort(key=lambda e: (e.package.lower(), e.version))
+    return entries
+
+
+def _cache_filename(
+    package_name: str,
+    version: str | None,
+    env_tag: str | None = None,
+) -> str:
     """Build the cache filename for a package.
 
     Sanitises both components to prevent path traversal via crafted
     package names (e.g. ``../../etc/cron.d/evil``).
+
+    When *env_tag* is provided (from ``--python``), it is appended to
+    the filename so that packages from different environments get
+    separate cache entries.
     """
     from ._security import sanitize_filename
 
     safe_name = sanitize_filename(package_name)
     safe_version = sanitize_filename(version) if version else "unknown"
+    if env_tag:
+        safe_tag = sanitize_filename(env_tag)
+        return f"{safe_name}-{safe_version}-{safe_tag}.json"
     return f"{safe_name}-{safe_version}.json"