releaseguru 0.1.0__tar.gz

releaseguru-0.1.0/.env.example

@@ -0,0 +1,11 @@
+# Copy this to .env and fill in only the key you want to use
+# Only ONE provider key is required, or you can pass them via CLI `--api-key`
+
+GROQ_API_KEY=gsk_...          # free at console.groq.com
+OPENAI_API_KEY=sk-...         # platform.openai.com
+ANTHROPIC_API_KEY=sk-ant-...  # console.anthropic.com
+GEMINI_API_KEY=AIza...        # aistudio.google.com (free)
+XAI_API_KEY=xai-...           # console.x.ai
+
+# Optional token for automated GitHub Release Publishing
+GITHUB_TOKEN=ghp_...          # personal access token with 'repo' scope

releaseguru-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,38 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install package and build tools
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m pip install -e .
+
+      - name: Run tests
+        run: python -m unittest discover -s tests
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package
+        run: python -m twine check dist/*
+
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1

releaseguru-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.env
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/

releaseguru-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ReleaseGuru 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.

releaseguru-0.1.0/PKG-INFO

@@ -0,0 +1,303 @@
+Metadata-Version: 2.4
+Name: releaseguru
+Version: 0.1.0
+Summary: AI release assistant CLI for git repositories.
+Project-URL: Homepage, https://github.com/ArhamAzeem/ReleaseGuru
+Project-URL: Repository, https://github.com/ArhamAzeem/ReleaseGuru
+Project-URL: Issues, https://github.com/ArhamAzeem/ReleaseGuru/issues
+Author: ReleaseGuru Contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,changelog,cli,github,release,semver
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Requires-Dist: anthropic>=0.30
+Requires-Dist: click>=8.0
+Requires-Dist: google-generativeai>=0.7
+Requires-Dist: groq>=0.9
+Requires-Dist: openai>=1.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: requests>=2.25
+Description-Content-Type: text/markdown
+
+# ReleaseGuru
+
+ReleaseGuru is an AI release assistant CLI for git repositories.
+
+Main feature: turn commit history into a release plan that tells the team what changed, what matters, what to test, and what can be published.
+
+Secondary helpers: version bumping, release notes, GitHub Releases, JSON output, and GitHub Actions outputs.
+
+## Features
+
+- AI release brief from git commits
+- Release summary, highlights, risks, checks, and user-facing notes
+- SemVer recommendation: `major`, `minor`, or `patch`
+- Auto-version from latest git tag
+- Manual version override
+- Markdown or JSON output
+- Notes-only mode for GitHub release bodies
+- Dry-run mode for CI and review
+- GitHub Release publish
+- Draft and prerelease publish modes
+- GitHub repo override with `--github-repo`
+- Optional tag creation and push
+- GitHub Actions output support with `--ci-output`
+- Multi-provider support: Groq, Gemini, OpenAI, Anthropic, xAI
+
+## Install
+
+After PyPI publish:
+
+```bash
+pipx install releaseguru
+```
+
+Or:
+
+```bash
+pip install releaseguru
+```
+
+During local development:
+
+```bash
+cd ReleaseGuru
+python -m venv venv
+pip install -e .
+cp .env.example .env
+```
+
+Add one AI provider key to `.env`.
+
+```env
+GROQ_API_KEY=
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+GEMINI_API_KEY=
+XAI_API_KEY=
+GITHUB_TOKEN=
+```
+
+`GITHUB_TOKEN` is only needed when publishing.
+
+## Basic Use
+
+Generate release plan:
+
+```bash
+releaseguru
+```
+
+Use custom range:
+
+```bash
+releaseguru --from v1.2.0 --to HEAD
+```
+
+Save to file:
+
+```bash
+releaseguru --output RELEASE.md
+```
+
+Generate JSON for automation:
+
+```bash
+releaseguru --format json --output release.json
+```
+
+Only print release notes:
+
+```bash
+releaseguru --notes-only
+```
+
+Dry run publish flow:
+
+```bash
+releaseguru --publish --dry-run --github-repo owner/repo
+```
+
+Publish full release:
+
+```bash
+releaseguru --publish
+```
+
+Publish only notes body:
+
+```bash
+releaseguru --publish --notes-only
+```
+
+Publish draft:
+
+```bash
+releaseguru --publish --draft
+```
+
+Publish prerelease:
+
+```bash
+releaseguru --publish --prerelease
+```
+
+Publish without creating/pushing a local tag:
+
+```bash
+releaseguru --publish --skip-tag
+```
+
+## GitHub Actions
+
+Use this when you want manual release from Actions.
+
+```yaml
+name: ReleaseGuru
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install ReleaseGuru
+        run: pip install releaseguru
+      - name: Create release
+        id: releaseguru
+        env:
+          GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: releaseguru --publish --notes-only --ci-output
+
+      - name: Show result
+        run: |
+          echo "Version: ${{ steps.releaseguru.outputs.version }}"
+          echo "Bump: ${{ steps.releaseguru.outputs.bump_type }}"
+          echo "URL: ${{ steps.releaseguru.outputs.release_url }}"
+```
+
+For review before publishing:
+
+```yaml
+- name: Preview release
+  env:
+    GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
+  run: releaseguru --dry-run --format json --output release.json
+```
+
+## Testing
+
+Syntax check:
+
+```bash
+python -m py_compile releaseguru/cli.py releaseguru/providers.py
+```
+
+Unit tests:
+
+```bash
+python -m unittest discover -s tests
+```
+
+CLI dry run with mocked AI response:
+
+```bash
+releaseguru --mock-response tests/fixtures/ai_response.txt --dry-run
+```
+
+Real AI test:
+
+```bash
+releaseguru --provider groq --dry-run
+```
+
+Real GitHub publish test:
+
+```bash
+releaseguru --provider groq --publish --draft
+```
+
+Use `--draft` first so you can inspect the release before making it public.
+
+## Release Ways
+
+- Local preview: `releaseguru --dry-run`
+- Local file: `releaseguru --output RELEASE.md`
+- CI preview: `releaseguru --format json --ci-output`
+- GitHub draft: `releaseguru --publish --draft`
+- GitHub prerelease: `releaseguru --publish --prerelease`
+- GitHub stable release: `releaseguru --publish`
+- Notes-only release body: `releaseguru --publish --notes-only`
+- Existing tag release: `releaseguru --publish --skip-tag --version v1.2.3`
+- Manual version release: `releaseguru --version v2.0.0 --publish`
+
+## Publish To PyPI
+
+Build package:
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+```
+
+Check package:
+
+```bash
+python -m twine check dist/*
+```
+
+Upload to TestPyPI first:
+
+```bash
+python -m twine upload --repository testpypi dist/*
+```
+
+Install from TestPyPI:
+
+```bash
+pipx install --index-url https://test.pypi.org/simple/ --pip-args="--extra-index-url https://pypi.org/simple/" releaseguru
+```
+
+Upload to real PyPI:
+
+```bash
+python -m twine upload dist/*
+```
+
+GitHub Actions publishing is also included in `.github/workflows/publish-pypi.yml`.
+For tokenless publishing, configure PyPI Trusted Publishing for this repository and publish a GitHub Release.
+
+## Provider Defaults
+
+| Provider | Option | Default model |
+|---|---|---|
+| Groq | `--provider groq` | `llama-3.3-70b-versatile` |
+| Gemini | `--provider gemini` | `gemini-1.5-flash` |
+| OpenAI | `--provider openai` | `gpt-4o-mini` |
+| Anthropic | `--provider anthropic` | `claude-3-5-haiku-20241022` |
+| xAI | `--provider xai` | `grok-3-mini` |

releaseguru-0.1.0/README.md

@@ -0,0 +1,271 @@
+# ReleaseGuru
+
+ReleaseGuru is an AI release assistant CLI for git repositories.
+
+Main feature: turn commit history into a release plan that tells the team what changed, what matters, what to test, and what can be published.
+
+Secondary helpers: version bumping, release notes, GitHub Releases, JSON output, and GitHub Actions outputs.
+
+## Features
+
+- AI release brief from git commits
+- Release summary, highlights, risks, checks, and user-facing notes
+- SemVer recommendation: `major`, `minor`, or `patch`
+- Auto-version from latest git tag
+- Manual version override
+- Markdown or JSON output
+- Notes-only mode for GitHub release bodies
+- Dry-run mode for CI and review
+- GitHub Release publish
+- Draft and prerelease publish modes
+- GitHub repo override with `--github-repo`
+- Optional tag creation and push
+- GitHub Actions output support with `--ci-output`
+- Multi-provider support: Groq, Gemini, OpenAI, Anthropic, xAI
+
+## Install
+
+After PyPI publish:
+
+```bash
+pipx install releaseguru
+```
+
+Or:
+
+```bash
+pip install releaseguru
+```
+
+During local development:
+
+```bash
+cd ReleaseGuru
+python -m venv venv
+pip install -e .
+cp .env.example .env
+```
+
+Add one AI provider key to `.env`.
+
+```env
+GROQ_API_KEY=
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+GEMINI_API_KEY=
+XAI_API_KEY=
+GITHUB_TOKEN=
+```
+
+`GITHUB_TOKEN` is only needed when publishing.
+
+## Basic Use
+
+Generate release plan:
+
+```bash
+releaseguru
+```
+
+Use custom range:
+
+```bash
+releaseguru --from v1.2.0 --to HEAD
+```
+
+Save to file:
+
+```bash
+releaseguru --output RELEASE.md
+```
+
+Generate JSON for automation:
+
+```bash
+releaseguru --format json --output release.json
+```
+
+Only print release notes:
+
+```bash
+releaseguru --notes-only
+```
+
+Dry run publish flow:
+
+```bash
+releaseguru --publish --dry-run --github-repo owner/repo
+```
+
+Publish full release:
+
+```bash
+releaseguru --publish
+```
+
+Publish only notes body:
+
+```bash
+releaseguru --publish --notes-only
+```
+
+Publish draft:
+
+```bash
+releaseguru --publish --draft
+```
+
+Publish prerelease:
+
+```bash
+releaseguru --publish --prerelease
+```
+
+Publish without creating/pushing a local tag:
+
+```bash
+releaseguru --publish --skip-tag
+```
+
+## GitHub Actions
+
+Use this when you want manual release from Actions.
+
+```yaml
+name: ReleaseGuru
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install ReleaseGuru
+        run: pip install releaseguru
+      - name: Create release
+        id: releaseguru
+        env:
+          GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: releaseguru --publish --notes-only --ci-output
+
+      - name: Show result
+        run: |
+          echo "Version: ${{ steps.releaseguru.outputs.version }}"
+          echo "Bump: ${{ steps.releaseguru.outputs.bump_type }}"
+          echo "URL: ${{ steps.releaseguru.outputs.release_url }}"
+```
+
+For review before publishing:
+
+```yaml
+- name: Preview release
+  env:
+    GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
+  run: releaseguru --dry-run --format json --output release.json
+```
+
+## Testing
+
+Syntax check:
+
+```bash
+python -m py_compile releaseguru/cli.py releaseguru/providers.py
+```
+
+Unit tests:
+
+```bash
+python -m unittest discover -s tests
+```
+
+CLI dry run with mocked AI response:
+
+```bash
+releaseguru --mock-response tests/fixtures/ai_response.txt --dry-run
+```
+
+Real AI test:
+
+```bash
+releaseguru --provider groq --dry-run
+```
+
+Real GitHub publish test:
+
+```bash
+releaseguru --provider groq --publish --draft
+```
+
+Use `--draft` first so you can inspect the release before making it public.
+
+## Release Ways
+
+- Local preview: `releaseguru --dry-run`
+- Local file: `releaseguru --output RELEASE.md`
+- CI preview: `releaseguru --format json --ci-output`
+- GitHub draft: `releaseguru --publish --draft`
+- GitHub prerelease: `releaseguru --publish --prerelease`
+- GitHub stable release: `releaseguru --publish`
+- Notes-only release body: `releaseguru --publish --notes-only`
+- Existing tag release: `releaseguru --publish --skip-tag --version v1.2.3`
+- Manual version release: `releaseguru --version v2.0.0 --publish`
+
+## Publish To PyPI
+
+Build package:
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+```
+
+Check package:
+
+```bash
+python -m twine check dist/*
+```
+
+Upload to TestPyPI first:
+
+```bash
+python -m twine upload --repository testpypi dist/*
+```
+
+Install from TestPyPI:
+
+```bash
+pipx install --index-url https://test.pypi.org/simple/ --pip-args="--extra-index-url https://pypi.org/simple/" releaseguru
+```
+
+Upload to real PyPI:
+
+```bash
+python -m twine upload dist/*
+```
+
+GitHub Actions publishing is also included in `.github/workflows/publish-pypi.yml`.
+For tokenless publishing, configure PyPI Trusted Publishing for this repository and publish a GitHub Release.
+
+## Provider Defaults
+
+| Provider | Option | Default model |
+|---|---|---|
+| Groq | `--provider groq` | `llama-3.3-70b-versatile` |
+| Gemini | `--provider gemini` | `gemini-1.5-flash` |
+| OpenAI | `--provider openai` | `gpt-4o-mini` |
+| Anthropic | `--provider anthropic` | `claude-3-5-haiku-20241022` |
+| xAI | `--provider xai` | `grok-3-mini` |

releaseguru-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "releaseguru"
+version = "0.1.0"
+description = "AI release assistant CLI for git repositories."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "ReleaseGuru Contributors" }
+]
+keywords = ["release", "changelog", "github", "cli", "ai", "semver"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Version Control :: Git",
+  "Topic :: Software Development :: Build Tools",
+]
+dependencies = [
+  "click>=8.0",
+  "groq>=0.9",
+  "openai>=1.0",
+  "anthropic>=0.30",
+  "google-generativeai>=0.7",
+  "python-dotenv>=1.0",
+  "requests>=2.25",
+]
+
+[project.urls]
+Homepage = "https://github.com/ArhamAzeem/ReleaseGuru"
+Repository = "https://github.com/ArhamAzeem/ReleaseGuru"
+Issues = "https://github.com/ArhamAzeem/ReleaseGuru/issues"
+
+[project.scripts]
+releaseguru = "releaseguru.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["releaseguru"]

releaseguru-0.1.0/releaseguru/__init__.py

@@ -0,0 +1,3 @@
+"""ReleaseGuru package."""
+
+__version__ = "0.1.0"

releaseguru-0.1.0/releaseguru/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()

releaseguru-0.1.0/releaseguru/cli.py

@@ -0,0 +1,368 @@
+import json
+import os
+import re
+import subprocess
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+import click
+import requests
+from dotenv import load_dotenv
+
+from .providers import PROVIDERS, auto_detect_provider
+
+load_dotenv()
+
+
+@dataclass
+class ReleaseResult:
+    version: str
+    bump_type: str
+    release_brief: str
+    release_notes: str
+    commit_count: int
+    from_ref: str | None
+    to_ref: str
+    provider: str
+    published_url: str | None = None
+
+
+def run_git(args: list[str], check: bool = True) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        ["git", *args],
+        capture_output=True,
+        text=True,
+        check=check,
+    )
+
+
+def get_commits(from_ref: str | None, to_ref: str) -> list[str]:
+    range_spec = f"{from_ref}..{to_ref}" if from_ref else to_ref
+    result = run_git(["log", range_spec, "--pretty=format:%s (%an)"])
+    return [line.strip() for line in result.stdout.splitlines() if line.strip()]
+
+
+def get_latest_tag() -> str | None:
+    result = run_git(["describe", "--tags", "--abbrev=0"], check=False)
+    return result.stdout.strip() if result.returncode == 0 else None
+
+
+def get_github_repo_slug() -> str | None:
+    result = run_git(["remote", "get-url", "origin"], check=False)
+    if result.returncode != 0:
+        return None
+
+    match = re.search(r"github\.com[:/]([^/]+)/([^.]+)(?:\.git)?", result.stdout.strip())
+    if not match:
+        return None
+    return f"{match.group(1)}/{match.group(2)}"
+
+
+def tag_exists(tag_name: str) -> bool:
+    return run_git(["rev-parse", "-q", "--verify", f"refs/tags/{tag_name}"], check=False).returncode == 0
+
+
+def create_and_push_tag(tag_name: str, dry_run: bool) -> None:
+    if dry_run:
+        return
+
+    if not tag_exists(tag_name):
+        run_git(["tag", "-a", tag_name, "-m", f"Release {tag_name}"])
+
+    run_git(["push", "origin", tag_name])
+
+
+def bump_version(version: str, bump_type: str) -> str:
+    match = re.search(r"(\d+)\.(\d+)\.(\d+)", version)
+    if not match:
+        return f"{version}-{bump_type}-bump"
+
+    major, minor, patch = map(int, match.groups())
+    if bump_type == "major":
+        major += 1
+        minor = 0
+        patch = 0
+    elif bump_type == "minor":
+        minor += 1
+        patch = 0
+    else:
+        patch += 1
+
+    prefix = "v" if version.lower().startswith("v") else ""
+    return f"{prefix}{major}.{minor}.{patch}"
+
+
+def build_prompt(commits: list[str], current_version: str) -> str:
+    lines = "\n".join(f"- {commit}" for commit in commits)
+    return f"""You are a release assistant for software teams.
+
+Analyze the git commits and prepare a release brief for humans. Help the team decide what this release is, what matters most, what needs attention, and what can be published.
+
+You MUST start the response with this exact line:
+__RECOMMENDED_BUMP__: <major|minor|patch>
+
+After that, output valid Markdown with these sections in this order:
+# Release Assistant Brief
+## Release Summary
+## Highlights
+## Risks & Checks
+## Suggested Release Notes
+
+Rules:
+- The release summary must be 2 to 4 sentences.
+- Highlights must contain 3 to 6 bullets when possible.
+- Risks & Checks must focus on validation, regressions, migrations, or rollout concerns.
+- Suggested Release Notes must be user-facing and grouped under:
+  - ### Features
+  - ### Bug Fixes
+  - ### Breaking Changes
+  - ### Improvements
+- Skip empty sections inside Suggested Release Notes.
+- Use present tense.
+- Avoid internal jargon unless needed for risk explanation.
+- Mention breaking changes only when justified by commits.
+- Choose major for breaking changes, minor for new visible functionality, patch for fixes/internal improvements only.
+
+Current version context: {current_version}
+
+Commits:
+{lines}
+
+Output only the marker line and Markdown."""
+
+
+def parse_ai_response(ai_raw: str) -> tuple[str, str]:
+    bump_type = "patch"
+    body_lines: list[str] = []
+
+    for line in ai_raw.splitlines():
+        if line.startswith("__RECOMMENDED_BUMP__"):
+            match = re.search(r"__RECOMMENDED_BUMP__:\s*(major|minor|patch)", line, re.IGNORECASE)
+            if match:
+                bump_type = match.group(1).lower()
+            continue
+        body_lines.append(line)
+
+    return bump_type, "\n".join(body_lines).strip()
+
+
+def extract_release_notes(release_brief: str) -> str:
+    marker = "## Suggested Release Notes"
+    if marker not in release_brief:
+        return release_brief.strip()
+    return release_brief.split(marker, 1)[1].strip()
+
+
+def build_output_document(result: ReleaseResult) -> str:
+    header = [
+        f"# Release Plan {result.version}",
+        "",
+        f"- Recommended bump: `{result.bump_type}`",
+        f"- Commits analyzed: `{result.commit_count}`",
+        "",
+    ]
+    return "\n".join(header) + result.release_brief.strip() + "\n"
+
+
+def publish_github_release(
+    repo_slug: str,
+    tag_name: str,
+    name: str,
+    body: str,
+    token: str,
+    draft: bool,
+    prerelease: bool,
+    dry_run: bool,
+) -> str:
+    if dry_run:
+        return f"https://github.com/{repo_slug}/releases/tag/{tag_name}"
+
+    url = f"https://api.github.com/repos/{repo_slug}/releases"
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+    }
+    payload = {
+        "tag_name": tag_name,
+        "name": name,
+        "body": body,
+        "draft": draft,
+        "prerelease": prerelease,
+    }
+    response = requests.post(url, json=payload, headers=headers, timeout=30)
+    if response.status_code not in (200, 201):
+        raise click.ClickException(f"GitHub API error: {response.status_code} - {response.text}")
+    return response.json().get("html_url", "")
+
+
+def write_github_output(result: ReleaseResult) -> None:
+    output_path = os.environ.get("GITHUB_OUTPUT")
+    if not output_path:
+        return
+
+    lines = [
+        f"version={result.version}",
+        f"bump_type={result.bump_type}",
+        f"commit_count={result.commit_count}",
+    ]
+    if result.published_url:
+        lines.append(f"release_url={result.published_url}")
+
+    with open(output_path, "a", encoding="utf-8") as handle:
+        handle.write("\n".join(lines) + "\n")
+
+
+def render_result(result: ReleaseResult, output_format: str, notes_only: bool) -> str:
+    if output_format == "json":
+        return json.dumps(asdict(result), indent=2)
+    if notes_only:
+        return result.release_notes + "\n"
+    return build_output_document(result)
+
+
+def call_provider(provider: str, prompt: str, api_key: str | None, model: str | None, mock_response: str | None) -> str:
+    if mock_response:
+        return Path(mock_response).read_text(encoding="utf-8")
+    return PROVIDERS[provider](prompt, api_key=api_key, model=model)
+
+
+@click.command()
+@click.option("--from", "from_ref", default=None, help="Start tag/ref. Default: latest git tag")
+@click.option("--to", "to_ref", default="HEAD", help="End ref. Default: HEAD")
+@click.option("--version", default=None, help="Explicit release version")
+@click.option(
+    "--provider",
+    default=None,
+    type=click.Choice(["groq", "openai", "anthropic", "gemini", "xai"]),
+    help="LLM provider. Default: auto-detect from env keys",
+)
+@click.option("--api-key", default=None, help="Custom API key for the selected provider")
+@click.option("--model", default=None, help="Custom model name for the selected provider")
+@click.option("--publish", is_flag=True, help="Create GitHub release")
+@click.option("--dry-run", is_flag=True, help="Generate output without creating tags or GitHub releases")
+@click.option("--draft", is_flag=True, help="Publish GitHub release as draft")
+@click.option("--prerelease", is_flag=True, help="Publish GitHub release as prerelease")
+@click.option("--skip-tag", is_flag=True, help="Do not create or push a git tag before publishing")
+@click.option("--github-repo", default=None, help="GitHub repo slug, e.g. owner/repo")
+@click.option("--github-token", default=None, help="GitHub token. Default: GITHUB_TOKEN env var")
+@click.option("--output", type=click.Path(), default=None, help="Write output to file")
+@click.option("--format", "output_format", type=click.Choice(["markdown", "json"]), default="markdown")
+@click.option("--notes-only", is_flag=True, help="Print only Suggested Release Notes")
+@click.option("--ci-output", is_flag=True, help="Write version, bump_type, commit_count, release_url to GITHUB_OUTPUT")
+@click.option("--mock-response", default=None, hidden=True, help="Read AI response from file for tests")
+def main(
+    from_ref,
+    to_ref,
+    version,
+    provider,
+    api_key,
+    model,
+    publish,
+    dry_run,
+    draft,
+    prerelease,
+    skip_tag,
+    github_repo,
+    github_token,
+    output,
+    output_format,
+    notes_only,
+    ci_output,
+    mock_response,
+):
+    """Prepare, inspect, and optionally publish an AI-assisted release."""
+    latest_tag = get_latest_tag()
+    if not from_ref:
+        from_ref = latest_tag
+        if from_ref:
+            click.echo(f"Using latest tag: {from_ref}", err=True)
+
+    if not provider:
+        if mock_response:
+            provider = "mock"
+        elif api_key:
+            raise click.ClickException("Use --provider when passing --api-key.")
+        else:
+            try:
+                provider = auto_detect_provider()
+                click.echo(f"Using provider: {provider}", err=True)
+            except EnvironmentError as exc:
+                raise click.ClickException(str(exc))
+
+    try:
+        commits = get_commits(from_ref, to_ref)
+    except subprocess.CalledProcessError as exc:
+        detail = exc.stderr.strip() if exc.stderr else "Could not execute git log."
+        raise click.ClickException(f"Git error: {detail}")
+
+    if not commits:
+        raise click.ClickException("No commits found in that range.")
+
+    click.echo(f"Found {len(commits)} commits. Building release brief...", err=True)
+
+    current_version = version or latest_tag or "v0.0.0"
+    prompt = build_prompt(commits, current_version)
+
+    try:
+        ai_raw = call_provider(provider, prompt, api_key, model, mock_response)
+    except Exception as exc:
+        raise click.ClickException(f"Error calling {provider} provider: {exc}")
+
+    bump_type, release_brief = parse_ai_response(ai_raw)
+    if not version:
+        version = bump_version(latest_tag, bump_type) if latest_tag else "v1.0.0"
+        click.echo(f"Resolved release version: {version}", err=True)
+
+    result = ReleaseResult(
+        version=version,
+        bump_type=bump_type,
+        release_brief=release_brief,
+        release_notes=extract_release_notes(release_brief),
+        commit_count=len(commits),
+        from_ref=from_ref,
+        to_ref=to_ref,
+        provider=provider,
+    )
+
+    if publish:
+        token = github_token or os.environ.get("GITHUB_TOKEN")
+        if not token and not dry_run:
+            raise click.ClickException("GitHub token not found. Set GITHUB_TOKEN or pass --github-token.")
+
+        repo_slug = github_repo or get_github_repo_slug()
+        if not repo_slug:
+            raise click.ClickException("Could not detect GitHub repo. Pass --github-repo owner/repo.")
+
+        if not skip_tag:
+            try:
+                create_and_push_tag(version, dry_run)
+            except subprocess.CalledProcessError as exc:
+                detail = exc.stderr.strip() if exc.stderr else "Tag create/push failed."
+                raise click.ClickException(f"Git tag error: {detail}")
+
+        result.published_url = publish_github_release(
+            repo_slug=repo_slug,
+            tag_name=version,
+            name=f"Release {version}",
+            body=result.release_notes if notes_only else build_output_document(result),
+            token=token or "",
+            draft=draft,
+            prerelease=prerelease,
+            dry_run=dry_run,
+        )
+        click.echo(f"Release URL: {result.published_url}", err=True)
+
+    rendered = render_result(result, output_format, notes_only)
+    if output:
+        Path(output).write_text(rendered, encoding="utf-8")
+        click.echo(f"Saved output to {output}", err=True)
+    else:
+        click.echo(rendered)
+
+    if ci_output:
+        write_github_output(result)
+
+
+if __name__ == "__main__":
+    main()

releaseguru-0.1.0/releaseguru/providers.py

@@ -0,0 +1,105 @@
+import os
+
+
+def call_groq(prompt: str, api_key: str | None = None, model: str | None = None) -> str:
+    from groq import Groq
+
+    key = api_key or os.environ.get("GROQ_API_KEY")
+    if not key:
+        raise ValueError("GROQ_API_KEY not found in environment or passed as argument.")
+
+    client = Groq(api_key=key)
+    response = client.chat.completions.create(
+        model=model or "llama-3.3-70b-versatile",
+        messages=[{"role": "user", "content": prompt}],
+        max_tokens=1024,
+    )
+    return response.choices[0].message.content
+
+
+def call_openai(prompt: str, api_key: str | None = None, model: str | None = None) -> str:
+    from openai import OpenAI
+
+    key = api_key or os.environ.get("OPENAI_API_KEY")
+    if not key:
+        raise ValueError("OPENAI_API_KEY not found in environment or passed as argument.")
+
+    client = OpenAI(api_key=key)
+    response = client.chat.completions.create(
+        model=model or "gpt-4o-mini",
+        messages=[{"role": "user", "content": prompt}],
+        max_tokens=1024,
+    )
+    return response.choices[0].message.content
+
+
+def call_anthropic(prompt: str, api_key: str | None = None, model: str | None = None) -> str:
+    import anthropic
+
+    key = api_key or os.environ.get("ANTHROPIC_API_KEY")
+    if not key:
+        raise ValueError("ANTHROPIC_API_KEY not found in environment or passed as argument.")
+
+    client = anthropic.Anthropic(api_key=key)
+    response = client.messages.create(
+        model=model or "claude-3-5-haiku-20241022",
+        max_tokens=1024,
+        messages=[{"role": "user", "content": prompt}],
+    )
+    return response.content[0].text
+
+
+def call_gemini(prompt: str, api_key: str | None = None, model: str | None = None) -> str:
+    import google.generativeai as genai
+
+    key = api_key or os.environ.get("GEMINI_API_KEY")
+    if not key:
+        raise ValueError("GEMINI_API_KEY not found in environment or passed as argument.")
+
+    genai.configure(api_key=key)
+    model_instance = genai.GenerativeModel(model or "gemini-1.5-flash")
+    response = model_instance.generate_content(prompt)
+    return response.text
+
+
+def call_xai(prompt: str, api_key: str | None = None, model: str | None = None) -> str:
+    from openai import OpenAI
+
+    key = api_key or os.environ.get("XAI_API_KEY")
+    if not key:
+        raise ValueError("XAI_API_KEY not found in environment or passed as argument.")
+
+    client = OpenAI(api_key=key, base_url="https://api.x.ai/v1")
+    response = client.chat.completions.create(
+        model=model or "grok-3-mini",
+        messages=[{"role": "user", "content": prompt}],
+        max_tokens=1024,
+    )
+    return response.choices[0].message.content
+
+
+PROVIDERS = {
+    "groq": call_groq,
+    "openai": call_openai,
+    "anthropic": call_anthropic,
+    "gemini": call_gemini,
+    "xai": call_xai,
+}
+
+
+def auto_detect_provider() -> str:
+    for name, key in [
+        ("groq", "GROQ_API_KEY"),
+        ("gemini", "GEMINI_API_KEY"),
+        ("openai", "OPENAI_API_KEY"),
+        ("anthropic", "ANTHROPIC_API_KEY"),
+        ("xai", "XAI_API_KEY"),
+    ]:
+        if os.environ.get(key):
+            return name
+
+    raise EnvironmentError(
+        "No API key found. Set one of: GROQ_API_KEY, GEMINI_API_KEY, "
+        "OPENAI_API_KEY, ANTHROPIC_API_KEY, or XAI_API_KEY in your .env, "
+        "or pass a custom key via --api-key."
+    )

releaseguru-0.1.0/requirements.txt

@@ -0,0 +1,7 @@
+click>=8.0
+groq>=0.9
+openai>=1.0
+anthropic>=0.30
+google-generativeai>=0.7
+python-dotenv>=1.0
+requests>=2.25

releaseguru-0.1.0/tests/fixtures/ai_response.txt

@@ -0,0 +1,16 @@
+__RECOMMENDED_BUMP__: minor
+# Release Assistant Brief
+## Release Summary
+This release adds export support and improves release automation. It should be validated around generated release notes and publish flow.
+## Highlights
+- Add export support.
+- Improve GitHub release publishing.
+- Improve release validation.
+## Risks & Checks
+- Verify generated notes before publishing.
+- Confirm the target git tag is correct.
+## Suggested Release Notes
+### Features
+- Add export support.
+### Improvements
+- Improve release publishing flow.

releaseguru-0.1.0/tests/test_releaseguru.py

@@ -0,0 +1,58 @@
+import json
+import unittest
+
+from releaseguru import (
+    __version__,
+)
+from releaseguru.cli import ReleaseResult, bump_version, extract_release_notes, parse_ai_response, render_result
+
+
+class ReleaseGuruTests(unittest.TestCase):
+    def test_version_exists(self):
+        self.assertEqual(__version__, "0.1.0")
+
+    def test_bump_version(self):
+        self.assertEqual(bump_version("v1.2.3", "major"), "v2.0.0")
+        self.assertEqual(bump_version("v1.2.3", "minor"), "v1.3.0")
+        self.assertEqual(bump_version("v1.2.3", "patch"), "v1.2.4")
+
+    def test_parse_ai_response(self):
+        bump, body = parse_ai_response("__RECOMMENDED_BUMP__: minor\n# Release Assistant Brief")
+
+        self.assertEqual(bump, "minor")
+        self.assertEqual(body, "# Release Assistant Brief")
+
+    def test_extract_release_notes(self):
+        notes = extract_release_notes(
+            "# Release Assistant Brief\n"
+            "## Release Summary\n"
+            "Text\n"
+            "## Suggested Release Notes\n"
+            "### Features\n"
+            "- Add export"
+        )
+
+        self.assertEqual(notes, "### Features\n- Add export")
+
+    def test_render_json(self):
+        result = ReleaseResult(
+            version="v1.0.0",
+            bump_type="minor",
+            release_brief="# Brief",
+            release_notes="### Features\n- Add export",
+            commit_count=2,
+            from_ref="v0.9.0",
+            to_ref="HEAD",
+            provider="mock",
+        )
+
+        rendered = render_result(result, "json", notes_only=False)
+        payload = json.loads(rendered)
+
+        self.assertEqual(payload["version"], "v1.0.0")
+        self.assertEqual(payload["bump_type"], "minor")
+        self.assertEqual(payload["commit_count"], 2)
+
+
+if __name__ == "__main__":
+    unittest.main()