Metadata-Version: 2.4
Name: agent-atlas-map
Version: 0.1.0
Summary: Deterministic repository maps for coding agents.
Project-URL: Homepage, https://github.com/douglasmonsky/agent-atlas
Project-URL: Repository, https://github.com/douglasmonsky/agent-atlas
Project-URL: Issues, https://github.com/douglasmonsky/agent-atlas/issues
Author: Agent Atlas contributors
License: MIT
License-File: LICENSE
Keywords: agents,codebase,documentation,repository-map,static-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.11
Requires-Dist: griffe<3,>=2.1
Requires-Dist: watchfiles<2,>=1
Description-Content-Type: text/markdown

# Agent Atlas

![Agent Atlas — a trustworthy map before the search](https://raw.githubusercontent.com/douglasmonsky/agent-atlas/main/assets/agent-atlas-hero.png)

[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-38BDF8?logo=python&logoColor=white)](https://www.python.org/)
[![MIT License](https://img.shields.io/badge/License-MIT-818CF8.svg)](LICENSE)
[![Static analysis](https://img.shields.io/badge/analysis-static-FBBF24)](#limits-and-safety)

Agent Atlas generates a deterministic, static repository map for coding agents.
It uses Griffe to extract Python packages, public symbols, signatures,
annotations, docstrings, source locations, and local type references without
importing the project being mapped.

> No LLM calls. No target-code execution. No invented explanations.

Start with `MAP.md`, follow the package and module pages to the exact symbol,
then open the source. Use deeper graph tools only when relationships or impact
analysis actually matter.

## Install

```console
pip install agent-atlas-map
```

Python 3.11 or later is required. The `agent-atlas` and `repo-map` commands are
equivalent; `repo-map` is retained as a compatibility alias.

## Configure and run

Add a minimal configuration to the target repository's `pyproject.toml`:

```toml
[tool.repo-map]
source_roots = ["src"]
root_packages = ["my_package"]
```

`source_roots` defaults to `["src"]`. When `root_packages` is omitted, Agent
Atlas discovers importable packages and modules directly below each source
root. Output defaults to `.repo-map` and `MAP.md`; the paths and additional
filtering, policy, summary, and watch settings can be configured in the same
table.

```console
# Generate or update the map in the current repository.
agent-atlas build

# Fail when generated files are missing or differ from a fresh render.
agent-atlas check

# Generate once, then rebuild after debounced .py or .pyi source changes.
agent-atlas watch

# Run against another repository.
agent-atlas build --project-root /path/to/project
```

## Output and exit codes

`build` writes a generated `MAP.md` at the project root and a `.repo-map/`
directory containing `index.json`, package maps, and module maps. `check` does
not write files.

| Code | Meaning |
| --- | --- |
| 0 | Build succeeded, or `check` found current, policy-compliant output. |
| 1 | `check` found stale, missing, or unexpected generated output. |
| 2 | A configured public-API policy requirement was violated. |
| 3 | Generation, publication, or watch failed. |
| 4 | Command usage or repository-map configuration was invalid. |
| 130 | The process was interrupted. |

## Limits and safety

Agent Atlas is static analysis, not runtime introspection. Dynamically created
symbols, imports resolved only at runtime, generated source, and information
available only through execution may be absent or unresolved in the map.

Builds stage and validate output before publishing. Agent Atlas refuses to
replace output it cannot identify as its own and attempts rollback when a
publication step fails. Each target replacement is atomic on the local
filesystem, but `.repo-map/` and `MAP.md` are separate targets: a process or
filesystem failure between replacements cannot be made globally atomic. Keep
the generated files under version control or regenerate after an interrupted
build. Publication assumes a locally controlled checkout; it does not defend
against another process maliciously replacing target directories during the
publication window.

## Development

```console
uv sync --group dev
uv run pytest
uv run ruff check .
uv run mypy
uv build
```

## License

MIT. See [LICENSE](LICENSE).
