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
actionparameter 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
pip install swarmauri_toolkit_github
Poetry
poetry add swarmauri_toolkit_github
uv
# 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-dotenvis imported automatically—drop your token into a local.envfile (GITHUB_TOKEN=ghp_...) for quick experimentation.
Quick Start
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
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
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
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 exportGITHUB_TOKENbefore 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.
1 maintainer
Metadata
1 maintainer
Release files for swarmauri_toolkit_github 0.9.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| swarmauri_toolkit_github-0.9.0.tar.gz | 13.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| swarmauri_toolkit_github-0.9.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 29.2 kB
Release files / swarmauri_toolkit_github-0.9.0.tar.gz
| Download URL | swarmauri_toolkit_github-0.9.0.tar.gz |
|---|---|
| Size | 13.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7892fc55cb9f056dce7c2ce528833dd54a85cc0b931132a36a5e1aa131c55a21
|
|
BLAKE2b-256 checksum How to use checksums |
c0fdeb211ca0a46a0b9d6ba5bb5a615801739d2b31c15d33617b7a91d853e8a2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.0 {"installer":{"name":"uv","version":"0.11.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / swarmauri_toolkit_github-0.9.0-py3-none-any.whl
| Download URL | swarmauri_toolkit_github-0.9.0-py3-none-any.whl |
|---|---|
| Size | 16.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
09000f41c0fcb9ac47c028dc0b4ab279b1378b5d3ff4519deb2a9cf501ba3c76
|
|
BLAKE2b-256 checksum How to use checksums |
e94c0edf9d9a37e0a61015be1f2630292ee80eee22c1abd5c78f11660ee6dac4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.0 {"installer":{"name":"uv","version":"0.11.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
