Metadata-Version: 2.5
Name: agentic-pydoc
Version: 0.1.38
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

A Git repository with at least one commit is required. Initialize and analyze a Python project:

```bash
cd /path/to/python-project
git init
git add .
git commit -m "initial"

agentic-pydoc init             # Create .agentic-pydoc.toml
agentic-pydoc install-skill    # Install the agent skill (optional)
agentic-pydoc scan             # Full analysis + BASELINE = HEAD
```

This creates `.agentic-pydoc/` with the analysis index, modules, symbols,
relationships, and the `BASELINE` file (the SHA of the last documented commit).

## Incremental workflow

After code changes, commit and regenerate documentation:

```bash
git add .
git commit -m "change feature"
agentic-pydoc docs             # Diff BASELINE..HEAD, update docs, BASELINE = HEAD
```

`docs` only analyzes files changed since the baseline commit. Run
`agentic-pydoc status` to inspect HEAD, baseline, and pending changes, and
`agentic-pydoc check` to verify the project is ready.

## 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 init             # Initialize .agentic-pydoc.toml in a Git repo
agentic-pydoc scan             # Full scan, refuse to overwrite existing BASELINE
agentic-pydoc docs             # Incremental update since BASELINE (no --check = apply)
agentic-pydoc check            # Verify repo, config, baseline readiness
agentic-pydoc status           # Show HEAD, BASELINE, changes since baseline
agentic-pydoc update           # Incremental index update from last commit
agentic-pydoc install-skill    # Install the agent 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` only writes `.agentic-pydoc.toml`. Install the
`agentic-pydoc` skill separately:

```bash
agentic-pydoc install-skill
```

This installs `.agents/skills/agentic-pydoc/SKILL.md` (plus the
`agentic-pydoc-docs` and `agentic-pydoc-setup` skills). Pass `--overwrite` to
replace an existing installation. 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` and `agentic-pydoc install-skill` 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
