Metadata-Version: 2.5
Name: releasesmith
Version: 0.1.0
Summary: AI-powered changelog and release-notes generator for Git repositories
Project-URL: Homepage, https://github.com/JToSound/releasesmith
Project-URL: Repository, https://github.com/JToSound/releasesmith
Project-URL: Issues, https://github.com/JToSound/releasesmith/issues
Author: JToSound
License: MIT License
        
        Copyright (c) 2026 JToSound and releasesmith contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: changelog,conventional-commits,git,llm,release-notes
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
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: Topic :: Software Development :: Version Control
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.115
Requires-Dist: gitpython>=3.1
Requires-Dist: jinja2>=3.1
Requires-Dist: litellm>=1.44
Requires-Dist: pydantic-settings>=2.4
Requires-Dist: pydantic>=2.8
Requires-Dist: python-multipart>=0.0.32
Requires-Dist: rich>=13.7
Requires-Dist: tenacity>=9.0
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn>=0.30
Provides-Extra: web
Requires-Dist: fastapi>=0.115; extra == 'web'
Requires-Dist: uvicorn[standard]>=0.30; extra == 'web'
Description-Content-Type: text/markdown

# releasesmith

[![CI](https://github.com/JToSound/releasesmith/actions/workflows/ci.yml/badge.svg)](https://github.com/JToSound/releasesmith/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/releasesmith.svg)](https://pypi.org/project/releasesmith/)
[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue.svg)](https://www.python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
![Coverage](https://img.shields.io/badge/coverage-85%25-brightgreen)

**releasesmith** is an AI-powered changelog and release-notes generator for Git
repositories. One command turns commit history into structured, readable
release documentation, with deterministic rule-based parsing and optional LLM
enhancement.

- **Offline-first**: no API key? `--no-llm` still produces a useful changelog.
- **Deterministic-first**: rules classify commits; LLM is only an enhancer.
- **Safe-by-default**: read-only on your repository; atomic output writes.

## Features

- Parses Conventional Commits (`feat`, `fix`, `perf`, `refactor`, `docs`,
  `build`, `ci`, `test`, `chore`), scopes, `!` breaking markers and
  `BREAKING CHANGE:` footers.
- Extracts PR numbers, closing issue references, co-authors and trailers.
- Two-layer classification: offline rules first, batched validated LLM calls
  only for what rules cannot resolve (with tenacity retries and a safe
  deterministic fallback).
- Groups history into per-tag releases plus an `Unreleased` section with
  Keep a Changelog-style categories.
- Conservative deduplication — never merges breaking changes or entries with
  issue/PR references.
- Renderers: **Markdown**, **JSON**, **self-contained HTML** (dark mode,
  no CDN, no JS required), **Twitter/X thread drafts**.
- Optional LLM polish rewrites entry wording in batches without touching
  hashes, refs or technical facts.
- English (`en`) and Traditional Chinese (`zh-TW`) headings and UI strings.
- Local FastAPI web UI sharing the exact core pipeline with the CLI.
- Typer CLI with Rich panels: every error explains *what*, *why* and *how to
  fix* — without leaking secrets.

## Supported LLM providers

| Provider | Models via | Credential env var |
|---|---|---|
| OpenAI | `litellm` (`gpt-4o-mini`, …) | `OPENAI_API_KEY` |
| Anthropic | `litellm` (`anthropic/claude-*`) | `ANTHROPIC_API_KEY` |
| Ollama (local) | `litellm` (`ollama/llama3`, …) | none (`OLLAMA_API_BASE` optional) |

No key configured? Everything still works with `--no-llm`.

## Installation

```bash
# uv tool
uv tool install releasesmith

# pipx
pipx install releasesmith

# from source
git clone https://github.com/JToSound/releasesmith
cd releasesmith
uv sync --all-groups
uv run releasesmith --help
```

## Quick start

```bash
cd your-repo
releasesmith generate --no-llm     # writes CHANGELOG.md, fully offline
releasesmith preview --no-llm      # terminal preview, writes nothing
releasesmith stats                 # category chart, scopes, authors
```

## CLI examples

```bash
releasesmith generate --since v1.2.0                    # range-limited
releasesmith generate --format html --output site.html  # self-contained page
releasesmith generate --format json                     # machine-readable
releasesmith generate --lang zh-TW                      # 繁體中文標題
releasesmith generate --provider openai                 # + LLM classification
releasesmith generate --provider ollama --model ollama/llama3
releasesmith generate --polish                          # LLM wording polish
releasesmith generate --paths src tests                 # path-filtered
releasesmith generate --include-merge-commits           # keep merges
releasesmith generate --dry-run                         # never writes files
releasesmith diff v1.0.0 v1.1.0                         # entry-level diff
releasesmith tweet --since v1.4.0                       # X/Twitter draft
releasesmith init                                       # guided config setup
releasesmith serve --host 127.0.0.1 --port 8000         # local web UI
```

## Configuration

Copy [`.releasesmith.toml.example`](.releasesmith.toml.example) to your repo
root as `.releasesmith.toml`:

```toml
[releasesmith]
llm_provider = "openai"        # openai | anthropic | ollama | "" (offline)
model = "gpt-4o-mini"
language = "en"                # en | zh-TW
format = "markdown"
output_file = "CHANGELOG.md"

[releasesmith.github]
repo = "owner/repo"            # enables commit/PR/issue links

[releasesmith.prompts]
classify_system = ""           # optional prompt overrides (merged per-key)
summarize_system = ""
```

Precedence: CLI flags > `RELEASESMITH_*` env vars > `.releasesmith.toml` >
packaged defaults. Full field reference:
[docs/configuration.md](docs/configuration.md).

## GitHub Actions integration

```yaml
name: Changelog check
on: [pull_request]
permissions:
  contents: read
jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0          # full history for accurate ranges
      - uses: astral-sh/setup-uv@v5
        with:
          python-version: "3.12"
      - run: uv tool install releasesmith
      - run: releasesmith generate --no-llm --dry-run
```

This repository's own CI runs lint + format + mypy strict + tests with an
80% coverage gate on Python 3.11/3.12 (Linux + Windows); the release
workflow builds and validates distributions on `v*` tags with PyPI trusted
publishing scaffolding.

## HTML output

`--format html` emits one self-contained file: system font stack, inline CSS,
responsive layout, automatic dark mode via `prefers-color-scheme`, colour-coded
category badges, a version timeline, clickable short hashes when
`[releasesmith.github] repo` is set — all content escaped, no JavaScript and
no external resources required.

## Local Web UI

```bash
releasesmith serve                # http://127.0.0.1:8000
```

Server-rendered form: enter any local repository path, pick since/until,
format and language, then preview or download the generated document. The web
UI binds loopback only by default and shares the CLI's validation and
pipeline code.

## Privacy & security note

Commit text is transmitted to a third party **only when you enable an LLM
provider** (via config or flags, without `--no-llm`). For sensitive
repositories prefer `--no-llm` or self-hosted Ollama, and review history for
embedded secrets first. API keys are read exclusively from environment
variables and never written to config files, logs or reports.

## Development

```bash
git clone https://github.com/JToSound/releasesmith && cd releasesmith
uv sync --all-groups
uv run pre-commit install 2>/dev/null || true   # optional
uv run ruff check .                             # lint
uv run ruff format .                            # format
uv run mypy src                                 # strict types
uv run pytest --cov=releasesmith                # tests + coverage gate ≥80%
```

Architecture: `src/releasesmith/core` (models, git parser, classifiers,
generator, summarizer) → `src/releasesmith/renderers` (markdown/json/html/
twitter via packaged Jinja2 templates) → `src/releasesmith/cli.py` +
`src/releasesmith/web.py` (thin interfaces). Providers live in
`src/releasesmith/providers`; prompt templates in
`src/releasesmith/templates/prompts`.

## Contributing

Issues and pull requests are welcome. For non-trivial changes please open an
issue first; include tests for behavioural changes (`pytest`) and make sure
the quality gates above pass locally.

## License

[MIT](LICENSE) — © JToSound and contributors.
