| Name | b3th JSON |
| Version |
0.1.2
JSON |
| download |
| home_page | None |
| Summary | CLI that auto-generates commit messages and GitHub PR descriptions |
| upload_time | 2025-08-15 04:00:46 |
| maintainer | None |
| docs_url | None |
| author | Bethvour |
| requires_python | <4.0,>=3.9 |
| license | MIT |
| keywords |
git
cli
commit
pull-request
ai
groq
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<h1 align="center">b3th</h1>
<p align="center">
<em>AI-powered CLI that stages, commits, pushes, proposes merge resolutions, and opens pull-requests for you.</em><br>
<a href="https://github.com/bethvourc/b3th/actions"><img alt="CI badge" src="https://github.com/bethvourc/b3th/actions/workflows/ci.yml/badge.svg"></a>
</p>
## ✨ Features
| Command | What it does |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `b3th sync` | **Stage → commit → push** in one shot. b3th asks an LLM for a succinct commit subject + body, then runs `git add --all`, `git commit`, and `git push -u origin <branch>`. |
| `b3th prcreate` | Pushes the current branch (if needed), summarises commits + diff, and opens a GitHub pull-request, returning the PR URL. |
| `b3th prdraft` | Opens a **draft** pull-request (marked “Draft” on GitHub) after generating the title/body with the LLM. |
| `b3th stats` | Shows commit count, unique files touched, and line additions/deletions for a given time-frame (e.g. `--last 7d`). |
| `b3th summarize` | Uses an LLM to produce a one-paragraph summary of the last _N_ commits (default 10). |
| `b3th resolve` | Scans for Git **merge conflicts**, builds a per-file prompt, asks the LLM for a merged version, writes `<file>.resolved`; `--apply` overwrites originals with the suggestions. |
_(The legacy `b3th commit` still works but prints a deprecation warning and delegates to **sync**.)_
Under the hood, b3th leverages **Groq’s Chat Completions API** for language generation and the **GitHub REST API** for PR creation.
---
## Quick Install
### 1 · Prerequisites
- **Python ≥ 3.9**
- **Git** in your `PATH`.
- **Poetry** (preferred) or plain `pip`. <sub>Install Poetry → `curl -sSL https://install.python-poetry.org | python3 -`</sub>
### 2 · Install the package
<details>
<summary><strong>Option A – From PyPI</strong> (when published)</summary>
```bash
pipx install b3th # keeps deps isolated
# or
pip install --user b3th
```
> **Important:** Installing the package is not enough.
> You still must provide credentials (see **“Set up your secrets”** below) via:
>
> - exported environment variables, or
> - a **project-level `.env`** file, or
> - a **TOML config file** (see examples below).
</details>
<details>
<summary><strong>Option B – From source</strong> (recommended for contributors)</summary>
```bash
git clone https://github.com/bethvourc/b3th.git
cd b3th
poetry install
```
</details>
### 3 · Set up your secrets
You can provide credentials in **either** your shell environment, a **project `.env`**, or a **TOML config** file.
#### A) Environment variables or project `.env` (simplest)
Put this in your environment (e.g. `export` in shell init) **or** in a **project-level `.env`**:
```dotenv
# <repo>/.env (project-level)
GROQ_API_KEY="sk_live_xxx" # https://console.groq.com/keys
GITHUB_TOKEN="ghp_xxx" # PAT with repo scope → https://github.com/settings/tokens
# Optional
# GROQ_MODEL_ID="llama-3.3-70b-versatile"
```
> **How `.env` loading works**
>
> b3th auto-loads **the nearest `.env` in your project tree** (using `python-dotenv`’s `find_dotenv(usecwd=True)`).
> It does **not** automatically read `~/.env`. If you prefer user-level credentials, either export them in your shell or use the TOML option below.
#### B) TOML config file (good for user-level/global setup)
Create:
```
~/.config/b3th/config.toml
```
On macOS/Linux with XDG:
```
$XDG_CONFIG_HOME/b3th/config.toml
```
Or point to a custom file via:
```
B3TH_CONFIG=/path/to/config.toml
```
Example contents:
```toml
[github]
token = "ghp_xxx"
[groq]
api_key = "sk_live_xxx"
```
> **Precedence:** environment variables (including values loaded from the project `.env`) take priority over TOML.
> **Security tip:** Add `.env` to your `.gitignore` and avoid committing secrets.
### 4 · (Dev only) Install Git hooks
```bash
poetry run pre-commit install # auto-format & lint on each commit
```
---
## CLI Usage
```bash
# One-shot stage → commit → push
poetry run b3th sync # interactive
poetry run b3th sync -y # non-interactive
# Create a pull-request into 'main'
poetry run b3th prcreate # interactive
poetry run b3th prcreate -b develop -y # specify base branch, skip confirm
# Create a draft pull-request to 'main'
poetry run b3th prdraft # interactive confirm
poetry run b3th prdraft -b develop -y # specify base branch, skip confirm
# Git statistics (last 7 days)
poetry run b3th stats --last 7d
# Summarise last 15 commits
poetry run b3th summarize -n 15
# Generate conflict suggestions (writes *.resolved files)
poetry run b3th resolve
# Accept suggestions and overwrite originals
poetry run b3th resolve --apply
```
### Sync Demo
```text
$ b3th sync
Proposed commit message:
feat(utils): support .env loading
Load environment variables automatically from the nearest project .env
so users don't need to export them manually each session.
Proceed with commit & push? [y/N]: y
🚀 Synced! Commit pushed to origin.
```
### Stats Demo
```bash
$ b3th stats --last 7d
Commits: 14
Files: 6
Additions: +120
Deletions: -34
```
### Summarize Demo
```bash
$ b3th summarize -n 10
Introduce a comprehensive stats command, improve README instructions,
and fix a minor UI colour bug—enhancing insight, onboarding, and UX.
```
### Resolve Demo
```bash
# Create .resolved files next to conflicted originals
$ b3th resolve
🔍 Detecting conflicts & asking the LLM…
💡 Generated 2 *.resolved file(s).
Inspect the *.resolved files. Run again with --apply to accept.
# Overwrite originals with merged suggestions
$ b3th resolve --apply
✅ Originals overwritten with LLM suggestions.
```
### Conflict-Resolver Workflow
1. **Run** `b3th resolve` to generate `<file>.resolved` for each conflicted file.
2. **Review** the proposed merges; tweak if needed.
3. **Apply** with `b3th resolve --apply` to overwrite originals and remove the `.resolved` files.
4. **Commit** your merged changes.
---
## Releasing (GitHub Actions + Trusted Publisher)
1. `poetry version patch` (or `minor`/`major`) and commit.
2. Tag: `git tag -a v$(poetry version -s) -m "b3th v$(poetry version -s)" && git push origin v$(poetry version -s)`
3. The workflow builds and uploads to PyPI automatically.
---
## Contributing
1. Fork & clone.
2. `poetry install && pre-commit install`
3. Create a branch: `git switch -c feat/your-idea`
4. Run `pytest` before pushing.
5. Open a PR—b3th’s CI enforces **≥ 85 %** coverage.
---
## License
Licensed under the **MIT License** – see `LICENSE` for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "b3th",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "git, cli, commit, pull-request, ai, groq",
"author": "Bethvour",
"author_email": "bethvourc@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/7d/66/bca989191af0b10da41f476f94ca2dfae179a694ecd29c770d4d7fb8ed6d/b3th-0.1.2.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">b3th</h1>\n<p align=\"center\">\n <em>AI-powered CLI that stages, commits, pushes, proposes merge resolutions, and opens pull-requests for you.</em><br>\n <a href=\"https://github.com/bethvourc/b3th/actions\"><img alt=\"CI badge\" src=\"https://github.com/bethvourc/b3th/actions/workflows/ci.yml/badge.svg\"></a>\n</p>\n\n## \u2728 Features\n\n| Command | What it does |\n| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `b3th sync` | **Stage \u2192 commit \u2192 push** in one shot. b3th asks an LLM for a succinct commit subject + body, then runs `git add --all`, `git commit`, and `git push -u origin <branch>`. |\n| `b3th prcreate` | Pushes the current branch (if needed), summarises commits + diff, and opens a GitHub pull-request, returning the PR URL. |\n| `b3th prdraft` | Opens a **draft** pull-request (marked \u201cDraft\u201d on GitHub) after generating the title/body with the LLM. |\n| `b3th stats` | Shows commit count, unique files touched, and line additions/deletions for a given time-frame (e.g. `--last 7d`). |\n| `b3th summarize` | Uses an LLM to produce a one-paragraph summary of the last _N_ commits (default 10). |\n| `b3th resolve` | Scans for Git **merge conflicts**, builds a per-file prompt, asks the LLM for a merged version, writes `<file>.resolved`; `--apply` overwrites originals with the suggestions. |\n\n_(The legacy `b3th commit` still works but prints a deprecation warning and delegates to **sync**.)_\n\nUnder the hood, b3th leverages **Groq\u2019s Chat Completions API** for language generation and the **GitHub REST API** for PR creation.\n\n---\n\n## Quick Install\n\n### 1 \u00b7 Prerequisites\n\n- **Python \u2265 3.9**\n- **Git** in your `PATH`.\n- **Poetry** (preferred) or plain `pip`. <sub>Install Poetry \u2192 `curl -sSL https://install.python-poetry.org | python3 -`</sub>\n\n### 2 \u00b7 Install the package\n\n<details>\n<summary><strong>Option A \u2013 From PyPI</strong> (when published)</summary>\n\n```bash\npipx install b3th # keeps deps isolated\n# or\npip install --user b3th\n```\n\n> **Important:** Installing the package is not enough. \n> You still must provide credentials (see **\u201cSet up your secrets\u201d** below) via:\n>\n> - exported environment variables, or\n> - a **project-level `.env`** file, or\n> - a **TOML config file** (see examples below).\n\n</details>\n\n<details>\n<summary><strong>Option B \u2013 From source</strong> (recommended for contributors)</summary>\n\n```bash\ngit clone https://github.com/bethvourc/b3th.git\ncd b3th\npoetry install\n```\n\n</details>\n\n### 3 \u00b7 Set up your secrets\n\nYou can provide credentials in **either** your shell environment, a **project `.env`**, or a **TOML config** file.\n\n#### A) Environment variables or project `.env` (simplest)\n\nPut this in your environment (e.g. `export` in shell init) **or** in a **project-level `.env`**:\n\n```dotenv\n# <repo>/.env (project-level)\nGROQ_API_KEY=\"sk_live_xxx\" # https://console.groq.com/keys\nGITHUB_TOKEN=\"ghp_xxx\" # PAT with repo scope \u2192 https://github.com/settings/tokens\n# Optional\n# GROQ_MODEL_ID=\"llama-3.3-70b-versatile\"\n```\n\n> **How `.env` loading works**\n>\n> b3th auto-loads **the nearest `.env` in your project tree** (using `python-dotenv`\u2019s `find_dotenv(usecwd=True)`). \n> It does **not** automatically read `~/.env`. If you prefer user-level credentials, either export them in your shell or use the TOML option below.\n\n#### B) TOML config file (good for user-level/global setup)\n\nCreate:\n\n```\n~/.config/b3th/config.toml\n```\n\nOn macOS/Linux with XDG:\n\n```\n$XDG_CONFIG_HOME/b3th/config.toml\n```\n\nOr point to a custom file via:\n\n```\nB3TH_CONFIG=/path/to/config.toml\n```\n\nExample contents:\n\n```toml\n[github]\ntoken = \"ghp_xxx\"\n\n[groq]\napi_key = \"sk_live_xxx\"\n```\n\n> **Precedence:** environment variables (including values loaded from the project `.env`) take priority over TOML.\n\n> **Security tip:** Add `.env` to your `.gitignore` and avoid committing secrets.\n\n### 4 \u00b7 (Dev only) Install Git hooks\n\n```bash\npoetry run pre-commit install # auto-format & lint on each commit\n```\n\n---\n\n## CLI Usage\n\n```bash\n# One-shot stage \u2192 commit \u2192 push\npoetry run b3th sync # interactive\npoetry run b3th sync -y # non-interactive\n\n# Create a pull-request into 'main'\npoetry run b3th prcreate # interactive\npoetry run b3th prcreate -b develop -y # specify base branch, skip confirm\n\n# Create a draft pull-request to 'main'\npoetry run b3th prdraft # interactive confirm\npoetry run b3th prdraft -b develop -y # specify base branch, skip confirm\n\n# Git statistics (last 7 days)\npoetry run b3th stats --last 7d\n\n# Summarise last 15 commits\npoetry run b3th summarize -n 15\n\n# Generate conflict suggestions (writes *.resolved files)\npoetry run b3th resolve\n\n# Accept suggestions and overwrite originals\npoetry run b3th resolve --apply\n```\n\n### Sync Demo\n\n```text\n$ b3th sync\nProposed commit message:\nfeat(utils): support .env loading\n\nLoad environment variables automatically from the nearest project .env\nso users don't need to export them manually each session.\n\nProceed with commit & push? [y/N]: y\n\ud83d\ude80 Synced! Commit pushed to origin.\n```\n\n### Stats Demo\n\n```bash\n$ b3th stats --last 7d\nCommits: 14\nFiles: 6\nAdditions: +120\nDeletions: -34\n```\n\n### Summarize Demo\n\n```bash\n$ b3th summarize -n 10\nIntroduce a comprehensive stats command, improve README instructions,\nand fix a minor UI colour bug\u2014enhancing insight, onboarding, and UX.\n```\n\n### Resolve Demo\n\n```bash\n# Create .resolved files next to conflicted originals\n$ b3th resolve\n\ud83d\udd0d Detecting conflicts & asking the LLM\u2026\n\ud83d\udca1 Generated 2 *.resolved file(s).\nInspect the *.resolved files. Run again with --apply to accept.\n\n# Overwrite originals with merged suggestions\n$ b3th resolve --apply\n\u2705 Originals overwritten with LLM suggestions.\n```\n\n### Conflict-Resolver Workflow\n\n1. **Run** `b3th resolve` to generate `<file>.resolved` for each conflicted file.\n2. **Review** the proposed merges; tweak if needed.\n3. **Apply** with `b3th resolve --apply` to overwrite originals and remove the `.resolved` files.\n4. **Commit** your merged changes.\n\n---\n\n## Releasing (GitHub Actions + Trusted Publisher)\n\n1. `poetry version patch` (or `minor`/`major`) and commit.\n2. Tag: `git tag -a v$(poetry version -s) -m \"b3th v$(poetry version -s)\" && git push origin v$(poetry version -s)`\n3. The workflow builds and uploads to PyPI automatically.\n\n---\n\n## Contributing\n\n1. Fork & clone.\n2. `poetry install && pre-commit install`\n3. Create a branch: `git switch -c feat/your-idea`\n4. Run `pytest` before pushing.\n5. Open a PR\u2014b3th\u2019s CI enforces **\u2265 85 %** coverage.\n\n---\n\n## License\n\nLicensed under the **MIT License** \u2013 see `LICENSE` for details.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "CLI that auto-generates commit messages and GitHub PR descriptions",
"version": "0.1.2",
"project_urls": {
"Bug Tracker": "https://github.com/bethvourc/b3th/issues",
"Homepage": "https://github.com/bethvourc/b3th",
"Repository": "https://github.com/bethvourc/b3th",
"Source": "https://github.com/bethvourc/b3th"
},
"split_keywords": [
"git",
" cli",
" commit",
" pull-request",
" ai",
" groq"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a531b63e1705b0c20c3d73aff913acc38bd18d58a9459183f3499431f2e66470",
"md5": "e06b1a337dd26192c252aee7e1e67f70",
"sha256": "7022b277061a2cf94f8dad80897756b33f3ef44f30a64df62215fa97edd84d7c"
},
"downloads": -1,
"filename": "b3th-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e06b1a337dd26192c252aee7e1e67f70",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 24251,
"upload_time": "2025-08-15T04:00:44",
"upload_time_iso_8601": "2025-08-15T04:00:44.232453Z",
"url": "https://files.pythonhosted.org/packages/a5/31/b63e1705b0c20c3d73aff913acc38bd18d58a9459183f3499431f2e66470/b3th-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7d66bca989191af0b10da41f476f94ca2dfae179a694ecd29c770d4d7fb8ed6d",
"md5": "6ce2db23470854f179712498c826020b",
"sha256": "710c13b7e0a20663818e17aa995390d9f9d40a47ae95625fddae2e9b7ac4e637"
},
"downloads": -1,
"filename": "b3th-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "6ce2db23470854f179712498c826020b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 21371,
"upload_time": "2025-08-15T04:00:46",
"upload_time_iso_8601": "2025-08-15T04:00:46.083007Z",
"url": "https://files.pythonhosted.org/packages/7d/66/bca989191af0b10da41f476f94ca2dfae179a694ecd29c770d4d7fb8ed6d/b3th-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-15 04:00:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bethvourc",
"github_project": "b3th",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "b3th"
}
