Metadata-Version: 2.4
Name: autoreadme-ai
Version: 0.1.2
Summary: Generate and maintain README files for Python repositories from static analysis.
Project-URL: Homepage, https://github.com/atharvakadam/autoreadme-ai
Project-URL: Issues, https://github.com/atharvakadam/autoreadme-ai/issues
Author-email: Atharva Kadam <atharvakadam@gmail.com>
License: MIT
License-File: LICENSE
Keywords: cli,documentation,generator,readme
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: typer>=0.12
Provides-Extra: all
Requires-Dist: anthropic>=0.40; extra == 'all'
Requires-Dist: openai>=1.50; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.40; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-mock>=3.12; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: openai
Requires-Dist: openai>=1.50; extra == 'openai'
Description-Content-Type: text/markdown

# AutoReadme

<!-- autoreadme:badges:start -->
[![PyPI version](https://img.shields.io/pypi/v/autoreadme-ai.svg?style=flat)](https://pypi.org/project/autoreadme-ai/) ![Python versions](https://img.shields.io/badge/python-%3E%3D3.11-blue.svg?style=flat) ![License](https://img.shields.io/badge/license-MIT-green.svg?style=flat) [![CI](https://github.com/atharvakadam/autoreadme-ai/actions/workflows/ci.yml/badge.svg)](https://github.com/atharvakadam/autoreadme-ai/actions/workflows/ci.yml) [![Downloads](https://img.shields.io/pypi/dm/autoreadme-ai.svg?style=flat)](https://pypi.org/project/autoreadme-ai/)
<!-- autoreadme:badges:end -->

Generate and maintain a README for your Python repo from static analysis — no
source code ever leaves your machine.

```bash
uvx --from 'autoreadme-ai' autoreadme .
```

AutoReadme walks your repo with the stdlib `ast` module, extracts structured
metadata (signatures, docstrings, project config, CLI parsers), and sends only
that metadata to an LLM to write prose. The payload schema has no field for
function bodies, so source code transmission isn't prevented by policy — it's
prevented by the shape of the data.

<!-- autoreadme:install:start -->
## Installation

```bash
uv tool install autoreadme-ai[anthropic,openai]
```

Install the tool as a command-line application using `uv`. The extras include optional dependencies for Anthropic and OpenAI providers. For one-shot usage without persistent installation, use `uvx autoreadme-ai[all]`. You can also install with `pipx install autoreadme-ai[all]` or `pip install autoreadme-ai`.
<!-- autoreadme:install:end -->

## Quick start

```bash
export ANTHROPIC_API_KEY=sk-...
autoreadme .
```

That's the whole flow: extract → pre-flight token check → single LLM call →
colored diff → approve (`Y/n/d/q`) → write with `.bak` backup.

Preview without writing:

```bash
autoreadme --dry-run
```

Inspect exactly what would be sent to the LLM (no network call):

```bash
autoreadme --show-payload
```

## How it protects your code

Three layers:

1. **Schema.** `RepoMetadata`, `FileMetadata`, `FunctionSignature` etc. have
   no `body` / `source` / `raw` field. There is no code path that can attach
   one.
2. **Pre-flight disclosure.** Before every LLM call, stderr shows exactly how
   many KB are about to leave your machine and where they're going:
   ```
   → Sending 14KB of structured metadata to anthropic (claude-sonnet-4-...).
     No source code included.
   ```
3. **`--show-payload`.** Dumps the full JSON to stdout and exits without
   making the call. Diff it, grep it, paste it into an issue.

Secret files (`.env*`, `*.key`, `*.pem`, `credentials.*`) are unconditionally
excluded from extraction regardless of config.

## Staying in sync

Generated sections are wrapped in HTML comment markers:

```markdown
<!-- autoreadme:install:start -->
(generated content)
<!-- autoreadme:install:end -->

## Docker Setup
(your content — never touched)
```

On subsequent runs, only content between markers is replaced. Manual sections
between, before, or after markers are preserved verbatim.

## Providers

| Provider  | Default model              | Env var             |
| --------- | -------------------------- | ------------------- |
| anthropic | `claude-sonnet-4-20250514` | `ANTHROPIC_API_KEY` |
| openai    | `gpt-4o`                   | `OPENAI_API_KEY`    |
| ollama    | `llama3.1`                 | `OLLAMA_HOST`       |

If no `--provider` is set, AutoReadme picks the one whose env var is
populated. Override the model with `--model` or `.autoreadme.toml`.

## Config file

Drop `.autoreadme.toml` at your repo root:

```toml
[llm]
provider = "anthropic"
model = "claude-sonnet-4-20250514"

[extract]
exclude = ["tests/**", "docs/**"]
```

Resolution precedence: **CLI flags > `.autoreadme.toml` > env vars > defaults.**

## GitHub Action

```yaml
- uses: atharvakadam/autoreadme-ai@v1
  with:
    provider: anthropic
    api-key: ${{ secrets.ANTHROPIC_API_KEY }}
```

The action runs with `--force` (non-interactive). Pair it with a PR-opening
step if you want review before merge.

<!-- autoreadme:cli_ref:start -->
## CLI Reference

```
autoreadme [PATH] [OPTIONS]
```

**Arguments:**
- `PATH` - Path to the repo root (default: `.`)

**Options:**
- `--provider` - LLM provider: anthropic | openai | ollama
- `--model` - Model override
- `--dry-run` - Write result to stdout instead of disk
- `--force` - Apply without interactive approval
- `--show-payload` - Dump JSON payload to stdout and exit
- `--verbose` - Verbose log output
- `--output` - Output path (default: <PATH>/README.md)
- `--version` - Print version and exit
<!-- autoreadme:cli_ref:end -->

Exit codes: `0` success · `1` user rejected diff · `2` config/usage/non-TTY ·
`3` extraction failed · `4` LLM failed.

## Scope

v0.1 is deliberately narrow. No monorepo handling, no section-level approval,
no custom prompt templates, no non-Python languages, no telemetry. See
[SPEC.md](SPEC.md) §15 for the full non-goals list and §16 for the v0.2 plan.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). TL;DR: `uv sync --all-extras`, then
`uv run pytest` / `uv run ruff check` / `uv run mypy src/` before opening a
PR.

## License

MIT — see [LICENSE](LICENSE).
