Metadata-Version: 2.5
Name: repomap-viz
Version: 0.1.0
Summary: Local-first interactive map of a Python project: modules, calls, entry points.
Author: Shahrukh Khan
License-Expression: MIT
License-File: LICENSE
Keywords: call-graph,code-map,fastapi,python,static-analysis,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
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: certifi>=2024.2.2
Requires-Dist: fastapi>=0.110
Requires-Dist: pathspec>=0.12
Requires-Dist: pydantic>=2.6
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn>=0.29
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# repomap

An interactive map of any Python project, running entirely on your machine.

```bash
pip install repomap-viz    # or run without installing: uvx --from repomap-viz repomap serve .
repomap serve ./my-project
```

Your browser opens on a GitHub-style view of the project:

- **Map**: modules, calls and class inheritance as a graph you can pan, zoom, filter by folder, and focus on one node. Circular imports are highlighted.
- **Trace**: pick an entry point (a FastAPI or Flask route, a Typer or Click command, a `__main__` block) and follow the calls step by step, with the code of each step.
- **Overview**: what's in the project, where execution starts, and which files failed to parse.
- **AI summaries** (optional): a 2–3 sentence explanation of any function, class or module, generated when you click it.

## Privacy

- Analysis is static. Your code is parsed, never imported or run.
- The server listens on `127.0.0.1` only and refuses requests from other websites.
- Nothing is written inside your project. The summary cache lives in `~/.cache/repomap/`.
- Code only leaves your machine if you turn on AI summaries, and then only the node you click **Summarize** on.

## AI summaries

Summaries use [NVIDIA's API](https://build.nvidia.com) with your own key:

```bash
export NVIDIA_API_KEY=nvapi-...
repomap serve ./my-project                          # default model: openai/gpt-oss-20b
repomap serve ./my-project --model z-ai/glm-5.3     # or any chat model NVIDIA hosts
repomap serve ./my-project --no-ai                  # never send anything
```

Each summary is cached by a hash of the code and the model name, so unchanged code is never sent twice.

## Commands

```bash
repomap serve PATH [--port 8765] [--no-ai] [--no-browser] [--model NAME]
repomap analyze PATH -o graph.json          # just the analysis, as JSON
repomap export PATH -o report.html          # one self-contained HTML file; add --no-source to leave code out
```

An exported report opens offline in any browser, with no server. It includes summaries that are already cached, and the source code unless you pass `--no-source`. Anyone you send it to can read everything in it.

## How call analysis stays honest

Python is dynamic, so a call graph built from source alone is always best-effort. repomap only draws an edge it can justify:

- **exact**: local functions, imported names (including `__init__` re-exports), `self.method()`, `super()`, `Class(...).method()`, with methods looked up through base classes.
- **inferred**: one plausible target, e.g. a parameter annotated with a project class, or a FastAPI `Depends(...)`.
- Everything else (`getattr`, callbacks, dictionary dispatch) is left out. A missing edge is better than a wrong one.

## Development

```bash
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/pytest
.venv/bin/python scripts/build_demo.py      # refresh the frontend demo data after analyzer changes
```

See `CLAUDE.md` for the architecture, the graph schema and the project rules.
