Metadata-Version: 2.5
Name: agentic-pydoc
Version: 0.1.19
Summary: Python codebase intelligence and documentation for AI agents.
License: MIT
Requires-Python: >=3.13
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.13.4
Requires-Dist: typer>=0.16.0
Description-Content-Type: text/markdown

# agentic-pydoc

Static Python codebase intelligence for AI agents.

## Installation

Requires Python 3.13+.

Install as an isolated tool (recommended):

```bash
uv tool install agentic-pydoc
```

Or with pipx:

```bash
python -m pip install --user pipx
python -m pipx ensurepath
pipx install agentic-pydoc
```

Then verify the install from any directory:

```bash
agentic-pydoc --help
agentic-pydoc --version
```

## Development

Contributors clone the repository and sync the environment instead:

```bash
git clone <repository-url>
cd agentic-pydoc
uv sync
uv run agentic-pydoc --help
```

## Quick Start

Initialize and analyze a Python project:

```bash
cd /path/to/python-project
agentic-pydoc init       # Create config and install skill
agentic-pydoc scan       # Initial analysis
```

This creates `.agentic-pydoc/` with the analysis index, modules, symbols, and relationships.

## MCP Server (New!)

Expose codebase intelligence to AI agents via Model Context Protocol:

```bash
cd /path/to/python-project
agentic-pydoc-mcp
```

The MCP server provides 9 tools for progressive codebase navigation:
- `list_modules` - List Python modules with pagination
- `get_module` - Get module details with symbols and imports
- `find_symbol` - Search for symbols by name/pattern
- `get_symbol` - Get full symbol details (signature, docstring, location)
- `get_behavior` - Get function behavior (raises, awaits, yields, returns)
- `get_callers` - Get all callers of a function/method
- `get_callees` - Get all callees of a symbol
- `get_inheritance` - Get class inheritance hierarchy
- `get_tests` - Get test cases for a symbol

See [MCP Server Documentation](docs/mcp-server.md) for complete API reference, examples, and integration guide.

### Architecture

```
Agent (LLM)
    ↓
MCP Protocol (JSON-RPC)
    ↓
MCP Server
    ↓
Service Layer
    ↓
Knowledge Navigator (shared with CLI)
    ↓
Knowledge Store
    ↓
.agentic-pydoc/
```

Both CLI and MCP use the same underlying service layer, ensuring consistent results.

## CLI Commands

### Analysis Commands

```bash
agentic-pydoc scan       # Full scan from scratch
agentic-pydoc update     # Incremental update from last commit
agentic-pydoc check      # Verify index is up to date
agentic-pydoc init       # Initialize config and install skill
```

### Navigation Commands

```bash
# Discovery
agentic-pydoc modules                           # List all modules
agentic-pydoc module <name>                     # Get module details
agentic-pydoc find <query>                      # Search for symbols
agentic-pydoc symbols --module <name>           # List symbols in module

# Symbol inspection
agentic-pydoc symbol <symbol-id>                # Get symbol details
agentic-pydoc source <symbol-id>                # Get source code
agentic-pydoc behavior <symbol-id>              # Get behavioral attributes

# Relationship navigation
agentic-pydoc callers <symbol-id>               # Who calls this?
agentic-pydoc callees <symbol-id>               # What does this call?
agentic-pydoc dependencies <symbol-id>          # All dependencies
agentic-pydoc dependents <symbol-id>            # All dependents
agentic-pydoc inheritance <class-id>            # Class hierarchy
agentic-pydoc tests <symbol-id>                 # Associated tests

# History
agentic-pydoc history                           # Git history
agentic-pydoc diff <rev-a> <rev-b>              # Semantic diff
```

All navigation commands support `--format json` for programmatic use.

## Project Intelligence vs Documentation

Three responsibilities stay separate:

- **Source code** is the source of truth.
- **`.agentic-pydoc/`** holds machine-readable project intelligence for agents:
  `index.json`, `state.json`, `modules/`, `symbols/`, `relationships/`.
- **`docs/`** holds human-facing documentation only.

`agentic-pydoc scan` writes the analysis under `.agentic-pydoc/` and the
machine-oriented renderings under `.agentic-pydoc/docs/` by default
(`output.directory` keeps custom locations when configured). It never writes
to `docs/` by default, and existing `docs/` content is left untouched.

## Using the Agent Skill

`agentic-pydoc init` installs the `agentic-pydoc` skill:

```bash
agentic-pydoc init
```

This writes `.agentic-pydoc.toml` when missing and installs
`.agents/skills/agentic-pydoc/SKILL.md`. The skill tells an agent to:
- **Prefer MCP** when a server is available
- Use CLI navigation commands as fallback
- Read `.agentic-pydoc/index.json` for project overview
- Treat analysis as context (not documentation)
- Never copy analysis into `docs/` or documentation sites
- Read source files when analysis is insufficient

### With Docus / create-docs

Run `agentic-pydoc init` in the analyzed project, then point `create-docs` at
the project. The skill instructs the agent to use `.agentic-pydoc/` (via MCP
or CLI) as context for understanding modules and symbols and to write
human-oriented documentation in `docs/` or the Docus site — not to copy the
analysis.

## Documentation

- [MCP Server](docs/mcp-server.md) - Complete MCP server reference
- [MCP Examples](docs/mcp-examples.md) - Usage examples and patterns
- [MCP Workflow](docs/mcp-workflow.md) - Agent workflow guide
- [MCP Limitations](docs/mcp-limitations.md) - Known constraints
- [API Reference](docs/API_REFERENCE.md) - CLI, models, analyzers
- [Incremental Indexing](docs/incremental-indexing.md) - Architecture details
- [Publishing](docs/publishing.md) - PyPI token authentication and publishing guide

## Testing

```bash
# All tests
uv run pytest

# MCP tests only
uv run pytest tests/mcp/ -v

# Specific test suites
uv run pytest tests/mcp/test_errors.py -v
uv run pytest tests/mcp/test_service.py -v
uv run pytest tests/mcp/test_server.py -v
uv run pytest tests/mcp/test_cli_mcp_consistency.py -v
```

## License

MIT
