pyenvsearch for ai agents

tl;dr

install:	`uv tool install pyenvsearch`
what:	python package exploration for ai coding agents
key features:	json output, enhanced object inspection, structured metadata
works with:	claude, gemini, codex, any llm with tool use
use cases:	understanding packages, finding apis, exploring codebases

overview

are you tired of claude or gemini making up completely imaginary classes, methods, or arguments? do you commonly work with private libraries or open source libraries whose APIs have changed since models were trained? if so, you probably want to try pyenvsearch.

pyenvsearch is a command-line tool built for ai coding agents. it provides LLMs with simple tools that they can use via command line to efficiently list, search, and understand installed libraries.

in particular, pyenvsearch helps to address the fact that most coding agents like Claude Code are designed to respect .gitignore files. this means that even though .venv folder might be within the claude or gemini working directory, their tools like ripgrep are unable to inspect or learn from the source code in site-packages.

the tool focuses on machine-readable information about package structure, virtual environments, and object metadata - the things agents need to generate working code based on the real library you installed, not the nonsense tokens that come from out-of-domain high-temperature sampling.

installation

cli tool installation

# recommended - install as cli tool
uv tool install pyenvsearch

# with performance enhancements (ast-grep, ripgrep)
uv tool install "pyenvsearch[performance]"

# alternative cli installer
pipx install pyenvsearch

# one-time usage without installation
uvx pyenvsearch --help

performance dependencies (optional)

for enhanced search performance, install these tools separately:

# macos
brew install ripgrep ast-grep

# ubuntu/debian
sudo apt install ripgrep
cargo install ast-grep-cli

# windows
winget install BurntSushi.ripgrep.MSVC
cargo install ast-grep-cli

core functionality

# find where a package is installed
pyenvsearch find fastapi
pyenvsearch find requests --json

shows package location, version, submodules, and distribution info.

table of contents generation

# generate package structure overview
pyenvsearch toc fastapi --depth 2

# show only public api (no underscore prefixes)
pyenvsearch toc fastapi --public --depth 3

example output:

Table of Contents: fastapi
==========================
Total Modules: 42
Total Classes: 89
Total Functions: 56

📄 applications (module)
📄 routing (module)
📦 security/
  📄 api_key (module)
  📄 http (module)
  📄 oauth2 (module)

code search capabilities

pattern searching

# search for classes containing "HTTP"
pyenvsearch search "class.*Http" --package requests

# find async functions
pyenvsearch search "async def" --package httpx --type regex

# semantic ast search
pyenvsearch search "class Response" --type ast

specific element discovery

# find class definitions
pyenvsearch class HttpClient --package httpx

# find method implementations
pyenvsearch method get --class HttpClient

# list all classes in a package
pyenvsearch list-classes requests --limit 20

# list methods with filtering
pyenvsearch list-methods httpx --include-private

enhanced object inspection

the enhanced dir() replacement provides rich metadata about python objects:

# import and use enhanced inspection
from pyenvsearch import enhanced_dir
import requests

# rich object exploration with type info and docs
enhanced_dir(requests, max_items=15, show_private=False)

example output:

🔍 Inspecting module: requests
📊 Showing 15 attributes (of 69 total)
================================================================================

📁 CLASS:
----------------------------------------
  📋 PreparedRequest (class) → The fully mutable PreparedRequest object
  📋 Request (class) → A user-created Request object
  📋 Response (class) → The Response object, which contains a
  📋 Session (class) → A Requests session

📁 EXCEPTION:
----------------------------------------
  📋 ConnectionError (exception) → A Connection error occurred
  📋 HTTPError (exception) → An HTTP error occurred
  📋 RequestException (exception) → There was an ambiguous exception

📁 METHOD:
----------------------------------------
  📋 get (method) (url, params=None, **kwargs) → Send GET request
  📋 post (method) (url, data=None, json=None, **kwargs) → Send POST request

programmatic object inspection

# get structured attribute data
from pyenvsearch import inspect_object, AttributeInfo
import pathlib

# analyze any python object
attrs = inspect_object(pathlib.Path, show_private=False, max_items=10)

# attrs is a list of AttributeInfo objects with:
# - name, type_description, signature
# - docstring_snippet, value_preview
# - is_private, module_origin

ai-powered analysis

when compatible llm tools are installed (claude, gemini, codex, goose):

# quick package overview
pyenvsearch summarize requests

# detailed technical explanation
pyenvsearch explain fastapi --tool claude

# generate how-to guides
pyenvsearch howto pandas --task "data cleaning"

# comprehensive api reference
pyenvsearch api-guide httpx

# ask specific questions
pyenvsearch ask requests "How do I handle timeouts?"

# check available ai tools
pyenvsearch llm-tools

practical examples

exploring unfamiliar packages

# just installed a new package - understand it quickly
pyenvsearch find pydantic              # where is it?
pyenvsearch toc pydantic --depth 2     # structure overview
pyenvsearch list-classes pydantic      # main classes
pyenvsearch class BaseModel            # specific class location

api discovery workflow

# find http-related functionality
pyenvsearch search "class.*Http" --package httpx
pyenvsearch method get --package httpx
pyenvsearch list-methods httpx --limit 20

# focus on public api only
pyenvsearch toc httpx --public --depth 2

debugging and investigation

# looking for validation functionality
pyenvsearch search "ValidationError" --package pydantic
pyenvsearch class ValidationError --package pydantic

# find all error classes
pyenvsearch search "class.*Error" --package requests

ai agent integration

all commands support --json for structured output that agents can parse:

# structured package information for agents
pyenvsearch find httpx --json | jq '.version'
pyenvsearch list-classes fastapi --json
pyenvsearch venv --json | jq '.packages[]'

# enhanced object inspection data for better code generation
python -c "
from pyenvsearch import inspect_object
import requests
attrs = inspect_object(requests, max_items=10)
for attr in attrs:
    print(f'{attr.name}: {attr.type_description}')
"

agent workflow examples

# help agents understand available packages
pyenvsearch venv --json

# provide detailed api surface for code generation
pyenvsearch toc fastapi --public --json

# give agents function signatures and documentation
pyenvsearch list-methods httpx --json | jq '.results[].signature'

limitations

ai features require external llm cli tools
enhanced search requires optional dependencies (ripgrep, ast-grep)
virtual environment detection works best with standard layouts
some package analysis requires packages to be importable

agent-optimized architecture

pyenvsearch is built with ai agents as the primary use case:

json-first design: all commands support structured output for machine consumption
zero dependencies: core functionality works in any python environment
comprehensive metadata: enhanced object inspection provides types, signatures, and docs agents need
performance optimizations: optional ast-grep and ripgrep for faster analysis
graceful degradation: works reliably across different environments

the structured output format allows agents to understand package capabilities and generate working code rather than hallucinating apis.