swarmauri_toolkit_github 0.8.0.dev4__tar.gz → 0.8.2__tar.gz

swarmauri_toolkit_github-0.8.2/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: swarmauri_toolkit_github
+Version: 0.8.2
+Summary: Github Toolkit
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: swarmauri,toolkit,github
+Author: Jacob Stewart
+Author-email: jacob@swarmauri.com
+Requires-Python: >=3.10,<3.13
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Natural Language :: English
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Dist: pygithub (>=2.4.0)
+Requires-Dist: swarmauri_base
+Requires-Dist: swarmauri_core
+Requires-Dist: swarmauri_standard
+Description-Content-Type: text/markdown
+
+![Swarmauri Logo](https://github.com/swarmauri/swarmauri-sdk/blob/3d4d1cfa949399d7019ae9d8f296afba773dfb7f/assets/swarmauri.brand.theme.svg)
+
+<p align="center">
+    <a href="https://pypi.org/project/swarmauri_toolkit_github/">
+        <img src="https://img.shields.io/pypi/dm/swarmauri_toolkit_github" alt="PyPI - Downloads"/></a>
+    <a href="https://hits.sh/github.com/swarmauri/swarmauri-sdk/tree/master/pkgs/community/swarmauri_toolkit_github/">
+        <img alt="Hits" src="https://hits.sh/github.com/swarmauri/swarmauri-sdk/tree/master/pkgs/community/swarmauri_toolkit_github.svg"/></a>
+    <a href="https://pypi.org/project/swarmauri_toolkit_github/">
+        <img src="https://img.shields.io/pypi/pyversions/swarmauri_toolkit_github" alt="PyPI - Python Version"/></a>
+    <a href="https://pypi.org/project/swarmauri_toolkit_github/">
+        <img src="https://img.shields.io/pypi/l/swarmauri_toolkit_github" alt="PyPI - License"/></a>
+    <a href="https://pypi.org/project/swarmauri_toolkit_github/">
+        <img src="https://img.shields.io/pypi/v/swarmauri_toolkit_github?label=swarmauri_toolkit_github&color=green" alt="PyPI - swarmauri_toolkit_github"/></a>
+</p>
+
+---
+
+# Swarmauri Toolkit · GitHub
+
+A Swarmauri toolkit that wraps PyGithub behind Swarmauri’s agent/tool abstractions. Authenticate once and gain access to repository, issue, pull request, branch, and commit helpers—ready for scripted automation or conversational agents.
+
+- Creates a shared GitHub client so every tool call reuses the same token and rate-limit state.
+- Normalizes responses into dictionaries so downstream logic can inspect status messages or raw PyGithub payloads.
+- Covers common actions (create/list/update/delete) while staying extensible via the `action` parameter on each tool.
+
+## Requirements
+
+- Python 3.10 – 3.13.
+- GitHub personal access token (classic or fine-grained) with the scopes your workflow requires. Store it in an environment variable such as `GITHUB_TOKEN`.
+- Runtime dependencies (`PyGithub`, `python-dotenv`, and the Swarmauri base/standard packages) install automatically with the toolkit.
+
+## Installation
+
+Choose any of the supported packaging flows; each command resolves transitive dependencies.
+
+**pip**
+
+```bash
+pip install swarmauri_toolkit_github
+```
+
+**Poetry**
+
+```bash
+poetry add swarmauri_toolkit_github
+```
+
+**uv**
+
+```bash
+# Add to the current project and update uv.lock
+uv add swarmauri_toolkit_github
+
+# or install into the active environment without editing pyproject.toml
+uv pip install swarmauri_toolkit_github
+```
+
+> Tip: `python-dotenv` is imported automatically—drop your token into a local `.env` file (`GITHUB_TOKEN=ghp_...`) for quick experimentation.
+
+## Quick Start
+
+```python
+import os
+from swarmauri_toolkit_github import GithubToolkit
+
+toolkit = GithubToolkit(api_token=os.environ["GITHUB_TOKEN"])
+
+# List repositories for the authenticated user
+repos = toolkit.github_repo_tool(action="list_repos")
+print(repos["list_repos"])
+
+# Open a tracking issue
+issue = toolkit.github_issue_tool(
+    action="create_issue",
+    repo_name="owner/example",
+    title="Investigate flaky tests",
+    body="Logs: https://gist.github.com/..."
+)
+print(issue["create_issue"])
+```
+
+Each sub-tool accepts an `action` argument (see PyGithub docs for additional options) and returns a dictionary keyed by that action for ergonomic unpacking.
+
+## Usage Scenarios
+
+### Automate Release Housekeeping
+
+```python
+from swarmauri_toolkit_github import GithubToolkit
+
+toolkit = GithubToolkit(api_token=os.environ["GITHUB_TOKEN"])
+
+# Create a release branch
+toolkit.github_branch_tool(
+    action="create_branch",
+    repo_name="owner/service",
+    new_branch="release/v1.4.0",
+    source_branch="master"
+)
+
+# Cut a changelog commit
+toolkit.github_commit_tool(
+    action="create_file",
+    repo_name="owner/service",
+    path="CHANGELOG.md",
+    message="Add release notes",
+    content="### v1.4.0\n- New features...",
+    branch="release/v1.4.0"
+)
+```
+
+### Drive GitHub From a Swarmauri Agent
+
+```python
+from swarmauri_core.agent.Agent import Agent
+from swarmauri_core.messages.HumanMessage import HumanMessage
+from swarmauri_standard.tools.registry import ToolRegistry
+from swarmauri_toolkit_github import GithubToolkit
+
+toolkit = GithubToolkit(api_token=os.environ["GITHUB_TOKEN"])
+registry = ToolRegistry()
+registry.register(toolkit.github_issue_tool)
+registry.register(toolkit.github_pr_tool)
+
+agent = Agent(tool_registry=registry)
+response = agent.run(HumanMessage(content="Open a PR from feature/auth to master"))
+print(response)
+```
+
+Enable conversational workflows that translate natural-language requests into GitHub mutations.
+
+### Triage Issues Nightly
+
+```python
+from datetime import datetime, timedelta
+from swarmauri_toolkit_github import GithubToolkit
+
+toolkit = GithubToolkit(api_token=os.environ["GITHUB_TOKEN"])
+cutoff = datetime.utcnow() - timedelta(days=7)
+
+issues = toolkit.github_issue_tool(
+    action="list",
+    repo_name="owner/product",
+    state="open"
+)["list"]
+
+stale = [issue for issue in issues if issue.updated_at < cutoff]
+for issue in stale:
+    toolkit.github_issue_tool(
+        action="create_comment",
+        repo_name="owner/product",
+        number=issue.number,
+        body="Ping! Any update in the last week?"
+    )
+```
+
+Keep a backlog tidy by automatically nudging stale tickets.
+
+## Troubleshooting
+
+- **`ValueError: Invalid Token or Missing api_token`** – Pass the token explicitly (`GithubToolkit(api_token=...)`) or export `GITHUB_TOKEN` before instantiating the toolkit.
+- **PyGithub exception messages** – Most actions bubble up PyGithub errors verbatim (permission issues, missing branches, etc.). Inspect the text in the returned string to resolve scope or naming problems.
+- **GitHub rate limits** – PyGithub tracks remaining requests; consider batching actions or sleeping when `Github.get_rate_limit()` indicates low headroom.
+
+## License
+
+`swarmauri_toolkit_github` is released under the Apache 2.0 License. See `LICENSE` for full details.
+

swarmauri_toolkit_github-0.8.2/README.md

@@ -0,0 +1,167 @@
+![Swarmauri Logo](https://github.com/swarmauri/swarmauri-sdk/blob/3d4d1cfa949399d7019ae9d8f296afba773dfb7f/assets/swarmauri.brand.theme.svg)
+
+<p align="center">
+    <a href="https://pypi.org/project/swarmauri_toolkit_github/">
+        <img src="https://img.shields.io/pypi/dm/swarmauri_toolkit_github" alt="PyPI - Downloads"/></a>
+    <a href="https://hits.sh/github.com/swarmauri/swarmauri-sdk/tree/master/pkgs/community/swarmauri_toolkit_github/">
+        <img alt="Hits" src="https://hits.sh/github.com/swarmauri/swarmauri-sdk/tree/master/pkgs/community/swarmauri_toolkit_github.svg"/></a>
+    <a href="https://pypi.org/project/swarmauri_toolkit_github/">
+        <img src="https://img.shields.io/pypi/pyversions/swarmauri_toolkit_github" alt="PyPI - Python Version"/></a>
+    <a href="https://pypi.org/project/swarmauri_toolkit_github/">
+        <img src="https://img.shields.io/pypi/l/swarmauri_toolkit_github" alt="PyPI - License"/></a>
+    <a href="https://pypi.org/project/swarmauri_toolkit_github/">
+        <img src="https://img.shields.io/pypi/v/swarmauri_toolkit_github?label=swarmauri_toolkit_github&color=green" alt="PyPI - swarmauri_toolkit_github"/></a>
+</p>
+
+---
+
+# Swarmauri Toolkit · GitHub
+
+A Swarmauri toolkit that wraps PyGithub behind Swarmauri’s agent/tool abstractions. Authenticate once and gain access to repository, issue, pull request, branch, and commit helpers—ready for scripted automation or conversational agents.
+
+- Creates a shared GitHub client so every tool call reuses the same token and rate-limit state.
+- Normalizes responses into dictionaries so downstream logic can inspect status messages or raw PyGithub payloads.
+- Covers common actions (create/list/update/delete) while staying extensible via the `action` parameter on each tool.
+
+## Requirements
+
+- Python 3.10 – 3.13.
+- GitHub personal access token (classic or fine-grained) with the scopes your workflow requires. Store it in an environment variable such as `GITHUB_TOKEN`.
+- Runtime dependencies (`PyGithub`, `python-dotenv`, and the Swarmauri base/standard packages) install automatically with the toolkit.
+
+## Installation
+
+Choose any of the supported packaging flows; each command resolves transitive dependencies.
+
+**pip**
+
+```bash
+pip install swarmauri_toolkit_github
+```
+
+**Poetry**
+
+```bash
+poetry add swarmauri_toolkit_github
+```
+
+**uv**
+
+```bash
+# Add to the current project and update uv.lock
+uv add swarmauri_toolkit_github
+
+# or install into the active environment without editing pyproject.toml
+uv pip install swarmauri_toolkit_github
+```
+
+> Tip: `python-dotenv` is imported automatically—drop your token into a local `.env` file (`GITHUB_TOKEN=ghp_...`) for quick experimentation.
+
+## Quick Start
+
+```python
+import os
+from swarmauri_toolkit_github import GithubToolkit
+
+toolkit = GithubToolkit(api_token=os.environ["GITHUB_TOKEN"])
+
+# List repositories for the authenticated user
+repos = toolkit.github_repo_tool(action="list_repos")
+print(repos["list_repos"])
+
+# Open a tracking issue
+issue = toolkit.github_issue_tool(
+    action="create_issue",
+    repo_name="owner/example",
+    title="Investigate flaky tests",
+    body="Logs: https://gist.github.com/..."
+)
+print(issue["create_issue"])
+```
+
+Each sub-tool accepts an `action` argument (see PyGithub docs for additional options) and returns a dictionary keyed by that action for ergonomic unpacking.
+
+## Usage Scenarios
+
+### Automate Release Housekeeping
+
+```python
+from swarmauri_toolkit_github import GithubToolkit
+
+toolkit = GithubToolkit(api_token=os.environ["GITHUB_TOKEN"])
+
+# Create a release branch
+toolkit.github_branch_tool(
+    action="create_branch",
+    repo_name="owner/service",
+    new_branch="release/v1.4.0",
+    source_branch="master"
+)
+
+# Cut a changelog commit
+toolkit.github_commit_tool(
+    action="create_file",
+    repo_name="owner/service",
+    path="CHANGELOG.md",
+    message="Add release notes",
+    content="### v1.4.0\n- New features...",
+    branch="release/v1.4.0"
+)
+```
+
+### Drive GitHub From a Swarmauri Agent
+
+```python
+from swarmauri_core.agent.Agent import Agent
+from swarmauri_core.messages.HumanMessage import HumanMessage
+from swarmauri_standard.tools.registry import ToolRegistry
+from swarmauri_toolkit_github import GithubToolkit
+
+toolkit = GithubToolkit(api_token=os.environ["GITHUB_TOKEN"])
+registry = ToolRegistry()
+registry.register(toolkit.github_issue_tool)
+registry.register(toolkit.github_pr_tool)
+
+agent = Agent(tool_registry=registry)
+response = agent.run(HumanMessage(content="Open a PR from feature/auth to master"))
+print(response)
+```
+
+Enable conversational workflows that translate natural-language requests into GitHub mutations.
+
+### Triage Issues Nightly
+
+```python
+from datetime import datetime, timedelta
+from swarmauri_toolkit_github import GithubToolkit
+
+toolkit = GithubToolkit(api_token=os.environ["GITHUB_TOKEN"])
+cutoff = datetime.utcnow() - timedelta(days=7)
+
+issues = toolkit.github_issue_tool(
+    action="list",
+    repo_name="owner/product",
+    state="open"
+)["list"]
+
+stale = [issue for issue in issues if issue.updated_at < cutoff]
+for issue in stale:
+    toolkit.github_issue_tool(
+        action="create_comment",
+        repo_name="owner/product",
+        number=issue.number,
+        body="Ping! Any update in the last week?"
+    )
+```
+
+Keep a backlog tidy by automatically nudging stale tickets.
+
+## Troubleshooting
+
+- **`ValueError: Invalid Token or Missing api_token`** – Pass the token explicitly (`GithubToolkit(api_token=...)`) or export `GITHUB_TOKEN` before instantiating the toolkit.
+- **PyGithub exception messages** – Most actions bubble up PyGithub errors verbatim (permission issues, missing branches, etc.). Inspect the text in the returned string to resolve scope or naming problems.
+- **GitHub rate limits** – PyGithub tracks remaining requests; consider batching actions or sleeping when `Github.get_rate_limit()` indicates low headroom.
+
+## License
+
+`swarmauri_toolkit_github` is released under the Apache 2.0 License. See `LICENSE` for full details.

{swarmauri_toolkit_github-0.8.0.dev4 → swarmauri_toolkit_github-0.8.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "swarmauri_toolkit_github"
-version = "0.8.0.dev4"
+version = "0.8.2"
 description = "Github Toolkit"
 license = "Apache-2.0"
 readme = "README.md"
@@ -11,6 +11,10 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Natural Language :: English",
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
 ]
 authors = [{ name = "Jacob Stewart", email = "jacob@swarmauri.com" }]
 dependencies = [
@@ -19,6 +23,11 @@ dependencies = [
     "swarmauri_base",
     "swarmauri_standard",
 ]
+keywords = [
+    "swarmauri",
+    "toolkit",
+    "github",
+]
 
 [tool.uv.sources]
 swarmauri_core = { workspace = true }

{swarmauri_toolkit_github-0.8.0.dev4 → swarmauri_toolkit_github-0.8.2}/swarmauri_toolkit_github/GithubBranchTool.py

@@ -71,7 +71,7 @@ class GithubBranchTool(ToolBase):
 
     # Branch Management Methods
     def create_branch(
-        self, repo_name: str, branch_name: str, source: str = "main"
+        self, repo_name: str, branch_name: str, source: str = "master"
     ) -> str:
         try:
             repo = self._github.get_repo(repo_name)

{swarmauri_toolkit_github-0.8.0.dev4 → swarmauri_toolkit_github-0.8.2}/swarmauri_toolkit_github/GithubCommitTool.py

@@ -106,7 +106,7 @@ class GithubCommitTool(ToolBase):
         file_path: str,
         message: str,
         content: str,
-        branch: str = "main",
+        branch: str = "master",
     ) -> str:
         try:
             repo = self._github.get_repo(repo_name)

swarmauri_toolkit_github-0.8.0.dev4/PKG-INFO

@@ -1,85 +0,0 @@
-Metadata-Version: 2.3
-Name: swarmauri_toolkit_github
-Version: 0.8.0.dev4
-Summary: Github Toolkit
-License: Apache-2.0
-Author: Jacob Stewart
-Author-email: jacob@swarmauri.com
-Requires-Python: >=3.10,<3.13
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Requires-Dist: pygithub (>=2.4.0)
-Requires-Dist: swarmauri_base
-Requires-Dist: swarmauri_core
-Requires-Dist: swarmauri_standard
-Description-Content-Type: text/markdown
-
-
-![Swamauri Logo](https://res.cloudinary.com/dbjmpekvl/image/upload/v1730099724/Swarmauri-logo-lockup-2048x757_hww01w.png)
-
-<p align="center">
-    <a href="https://pypi.org/project/swarmauri_toolkit_github/">
-        <img src="https://img.shields.io/pypi/dm/swarmauri_toolkit_github" alt="PyPI - Downloads"/></a>
-    <a href="https://hits.sh/github.com/swarmauri/swarmauri-sdk/tree/master/pkgs/community/swarmauri_toolkit_github/">
-        <img alt="Hits" src="https://hits.sh/github.com/swarmauri/swarmauri-sdk/tree/master/pkgs/community/swarmauri_toolkit_github.svg"/></a>
-    <a href="https://pypi.org/project/swarmauri_toolkit_github/">
-        <img src="https://img.shields.io/pypi/pyversions/swarmauri_toolkit_github" alt="PyPI - Python Version"/></a>
-    <a href="https://pypi.org/project/swarmauri_toolkit_github/">
-        <img src="https://img.shields.io/pypi/l/swarmauri_toolkit_github" alt="PyPI - License"/></a>
-    <a href="https://pypi.org/project/swarmauri_toolkit_github/">
-        <img src="https://img.shields.io/pypi/v/swarmauri_toolkit_github?label=swarmauri_toolkit_github&color=green" alt="PyPI - swarmauri_toolkit_github"/></a>
-</p>
-
----
-
-# Swarmauri Toolkit Github
-
-A collection of GitHub tools for repository, issue, pull request, branch, and commit management using PyGithub.
-
-## Installation
-
-```bash
-pip install swarmauri_toolkit_github
-```
-
-## Usage
-
-Here's a basic example using the GitHub toolkit:
-
-```python
-from swarmauri.toolkits.GithubToolkit import GithubToolkit
-
-# Initialize the toolkit with your GitHub token
-toolkit = GithubToolkit(token="your_github_token")
-
-# Create a repository
-result = toolkit.github_repo_tool(
-    action="create_repo",
-    repo_name="my-new-repo"
-)
-
-# Create an issue
-result = toolkit.github_issue_tool(
-    action="create_issue",
-    repo_name="owner/repository",
-    title="Bug Report",
-    body="Description of the issue"
-)
-
-# Create a pull request
-result = toolkit.github_pr_tool(
-    action="create_pull",
-    repo_name="owner/repository",
-    title="New Feature",
-    head="feature-branch",
-    base="main"
-)
-```
-
-## Want to help?
-
-If you want to contribute to swarmauri-sdk, read up on our [guidelines for contributing](https://github.com/swarmauri/swarmauri-sdk/blob/master/contributing.md) that will help you get started.
-
-

swarmauri_toolkit_github-0.8.0.dev4/README.md

@@ -1,66 +0,0 @@
-
-![Swamauri Logo](https://res.cloudinary.com/dbjmpekvl/image/upload/v1730099724/Swarmauri-logo-lockup-2048x757_hww01w.png)
-
-<p align="center">
-    <a href="https://pypi.org/project/swarmauri_toolkit_github/">
-        <img src="https://img.shields.io/pypi/dm/swarmauri_toolkit_github" alt="PyPI - Downloads"/></a>
-    <a href="https://hits.sh/github.com/swarmauri/swarmauri-sdk/tree/master/pkgs/community/swarmauri_toolkit_github/">
-        <img alt="Hits" src="https://hits.sh/github.com/swarmauri/swarmauri-sdk/tree/master/pkgs/community/swarmauri_toolkit_github.svg"/></a>
-    <a href="https://pypi.org/project/swarmauri_toolkit_github/">
-        <img src="https://img.shields.io/pypi/pyversions/swarmauri_toolkit_github" alt="PyPI - Python Version"/></a>
-    <a href="https://pypi.org/project/swarmauri_toolkit_github/">
-        <img src="https://img.shields.io/pypi/l/swarmauri_toolkit_github" alt="PyPI - License"/></a>
-    <a href="https://pypi.org/project/swarmauri_toolkit_github/">
-        <img src="https://img.shields.io/pypi/v/swarmauri_toolkit_github?label=swarmauri_toolkit_github&color=green" alt="PyPI - swarmauri_toolkit_github"/></a>
-</p>
-
----
-
-# Swarmauri Toolkit Github
-
-A collection of GitHub tools for repository, issue, pull request, branch, and commit management using PyGithub.
-
-## Installation
-
-```bash
-pip install swarmauri_toolkit_github
-```
-
-## Usage
-
-Here's a basic example using the GitHub toolkit:
-
-```python
-from swarmauri.toolkits.GithubToolkit import GithubToolkit
-
-# Initialize the toolkit with your GitHub token
-toolkit = GithubToolkit(token="your_github_token")
-
-# Create a repository
-result = toolkit.github_repo_tool(
-    action="create_repo",
-    repo_name="my-new-repo"
-)
-
-# Create an issue
-result = toolkit.github_issue_tool(
-    action="create_issue",
-    repo_name="owner/repository",
-    title="Bug Report",
-    body="Description of the issue"
-)
-
-# Create a pull request
-result = toolkit.github_pr_tool(
-    action="create_pull",
-    repo_name="owner/repository",
-    title="New Feature",
-    head="feature-branch",
-    base="main"
-)
-```
-
-## Want to help?
-
-If you want to contribute to swarmauri-sdk, read up on our [guidelines for contributing](https://github.com/swarmauri/swarmauri-sdk/blob/master/contributing.md) that will help you get started.
-