Skip to content

Commit c72f0d2

Browse files
ccurmeErick Friis
ccurme
and
Erick Friis
authored
docs: update toolkit integration pages (#24887)
Co-authored-by: Erick Friis <erick@langchain.dev>
1 parent 75776e4 commit c72f0d2

File tree

7 files changed

+824
-177
lines changed

7 files changed

+824
-177
lines changed

‎docs/docs/integrations/toolkits/github.ipynb

Lines changed: 163 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -4,60 +4,64 @@
44
"cell_type": "markdown",
55
"metadata": {},
66
"source": [
7-
"# Github\n",
7+
"---\n",
8+
"sidebar_label: Github\n",
9+
"---"
10+
]
11+
},
12+
{
13+
"cell_type": "markdown",
14+
"metadata": {},
15+
"source": [
16+
"# GithubToolkit\n",
817
"\n",
918
"The `Github` toolkit contains tools that enable an LLM agent to interact with a github repository. \n",
1019
"The tool is a wrapper for the [PyGitHub](https://github.com/PyGithub/PyGithub) library. \n",
1120
"\n",
12-
"## Quickstart\n",
21+
"For detailed documentation of all GithubToolkit features and configurations head to the [API reference](https://api.python.langchain.com/en/latest/agent_toolkits/langchain_community.agent_toolkits.github.toolkit.GitHubToolkit.html).\n",
22+
"\n",
23+
"## Setup\n",
24+
"\n",
25+
"At a high-level, we will:\n",
1326
"\n",
1427
"1. Install the pygithub library\n",
1528
"2. Create a Github app\n",
1629
"3. Set your environmental variables\n",
17-
"4. Pass the tools to your agent with `toolkit.get_tools()`\n",
18-
"\n",
19-
"Each of these steps will be explained in great detail below.\n",
20-
"\n",
21-
"1. **Get Issues**- fetches issues from the repository.\n",
22-
"\n",
23-
"2. **Get Issue**- fetches details about a specific issue.\n",
24-
"\n",
25-
"3. **Comment on Issue**- posts a comment on a specific issue.\n",
26-
"\n",
27-
"4. **Create Pull Request**- creates a pull request from the bot's working branch to the base branch.\n",
28-
"\n",
29-
"5. **Create File**- creates a new file in the repository.\n",
30-
"\n",
31-
"6. **Read File**- reads a file from the repository.\n",
32-
"\n",
33-
"7. **Update File**- updates a file in the repository.\n",
34-
"\n",
35-
"8. **Delete File**- deletes a file from the repository.\n",
36-
"\n"
30+
"4. Pass the tools to your agent with `toolkit.get_tools()`"
3731
]
3832
},
3933
{
4034
"cell_type": "markdown",
4135
"metadata": {},
4236
"source": [
43-
"## Setup"
37+
"If you want to get automated tracing from runs of individual tools, you can also set your [LangSmith](https://docs.smith.langchain.com/) API key by uncommenting below:"
38+
]
39+
},
40+
{
41+
"cell_type": "code",
42+
"execution_count": null,
43+
"metadata": {},
44+
"outputs": [],
45+
"source": [
46+
"# os.environ[\"LANGSMITH_API_KEY\"] = getpass.getpass(\"Enter your LangSmith API key: \")\n",
47+
"# os.environ[\"LANGSMITH_TRACING\"] = \"true\""
4448
]
4549
},
4650
{
4751
"cell_type": "markdown",
4852
"metadata": {},
4953
"source": [
50-
"### 1. Install the `pygithub` library "
54+
"### Installation\n",
55+
"\n",
56+
"#### 1. Install dependencies\n",
57+
"\n",
58+
"This integration is implemented in `langchain-community`. We will also need the `pygithub` dependency:"
5159
]
5260
},
5361
{
5462
"cell_type": "code",
5563
"execution_count": null,
56-
"metadata": {
57-
"vscode": {
58-
"languageId": "shellscript"
59-
}
60-
},
64+
"metadata": {},
6165
"outputs": [],
6266
"source": [
6367
"%pip install --upgrade --quiet pygithub langchain-community"
@@ -67,7 +71,7 @@
6771
"cell_type": "markdown",
6872
"metadata": {},
6973
"source": [
70-
"### 2. Create a Github App\n",
74+
"#### 2. Create a Github App\n",
7175
"\n",
7276
"[Follow the instructions here](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) to create and register a Github app. Make sure your app has the following [repository permissions:](https://docs.github.com/en/rest/overview/permissions-required-for-github-apps?apiVersion=2022-11-28)\n",
7377
"\n",
@@ -77,25 +81,139 @@
7781
"* Metadata (read only)\n",
7882
"* Pull requests (read and write)\n",
7983
"\n",
80-
"\n",
8184
"Once the app has been registered, you must give your app permission to access each of the repositories you whish it to act upon. Use the App settings on [github.com here](https://github.com/settings/installations).\n",
8285
"\n",
83-
"### 3. Set Environmental Variables\n",
8486
"\n",
85-
"Before initializing your agent, the following environmental variables need to be set:\n",
87+
"#### 3. Set Environment Variables\n",
88+
"\n",
89+
"Before initializing your agent, the following environment variables need to be set:\n",
8690
"\n",
8791
"* **GITHUB_APP_ID**- A six digit number found in your app's general settings\n",
8892
"* **GITHUB_APP_PRIVATE_KEY**- The location of your app's private key .pem file, or the full text of that file as a string.\n",
8993
"* **GITHUB_REPOSITORY**- The name of the Github repository you want your bot to act upon. Must follow the format {username}/{repo-name}. *Make sure the app has been added to this repository first!*\n",
9094
"* Optional: **GITHUB_BRANCH**- The branch where the bot will make its commits. Defaults to `repo.default_branch`.\n",
91-
"* Optional: **GITHUB_BASE_BRANCH**- The base branch of your repo upon which PRs will based from. Defaults to `repo.default_branch`.\n"
95+
"* Optional: **GITHUB_BASE_BRANCH**- The base branch of your repo upon which PRs will based from. Defaults to `repo.default_branch`."
96+
]
97+
},
98+
{
99+
"cell_type": "code",
100+
"execution_count": null,
101+
"metadata": {},
102+
"outputs": [],
103+
"source": [
104+
"import getpass\n",
105+
"import os\n",
106+
"\n",
107+
"for env_var in [\n",
108+
" \"GITHUB_APP_ID\",\n",
109+
" \"GITHUB_APP_PRIVATE_KEY\",\n",
110+
" \"GITHUB_REPOSITORY\",\n",
111+
"]:\n",
112+
" if not os.getenv(env_var):\n",
113+
" os.environ[env_var] = getpass.getpass()"
114+
]
115+
},
116+
{
117+
"cell_type": "markdown",
118+
"metadata": {},
119+
"source": [
120+
"## Instantiation\n",
121+
"\n",
122+
"Now we can instantiate our toolkit:"
123+
]
124+
},
125+
{
126+
"cell_type": "code",
127+
"execution_count": 6,
128+
"metadata": {},
129+
"outputs": [],
130+
"source": [
131+
"from langchain_community.agent_toolkits.github.toolkit import GitHubToolkit\n",
132+
"from langchain_community.utilities.github import GitHubAPIWrapper\n",
133+
"\n",
134+
"github = GitHubAPIWrapper()\n",
135+
"toolkit = GitHubToolkit.from_github_api_wrapper(github)"
136+
]
137+
},
138+
{
139+
"cell_type": "markdown",
140+
"metadata": {},
141+
"source": [
142+
"## Tools\n",
143+
"\n",
144+
"View available tools:"
145+
]
146+
},
147+
{
148+
"cell_type": "code",
149+
"execution_count": 9,
150+
"metadata": {},
151+
"outputs": [
152+
{
153+
"name": "stdout",
154+
"output_type": "stream",
155+
"text": [
156+
"Get Issues\n",
157+
"Get Issue\n",
158+
"Comment on Issue\n",
159+
"List open pull requests (PRs)\n",
160+
"Get Pull Request\n",
161+
"Overview of files included in PR\n",
162+
"Create Pull Request\n",
163+
"List Pull Requests' Files\n",
164+
"Create File\n",
165+
"Read File\n",
166+
"Update File\n",
167+
"Delete File\n",
168+
"Overview of existing files in Main branch\n",
169+
"Overview of files in current working branch\n",
170+
"List branches in this repository\n",
171+
"Set active branch\n",
172+
"Create a new branch\n",
173+
"Get files from a directory\n",
174+
"Search issues and pull requests\n",
175+
"Search code\n",
176+
"Create review request\n"
177+
]
178+
}
179+
],
180+
"source": [
181+
"tools = toolkit.get_tools()\n",
182+
"\n",
183+
"for tool in tools:\n",
184+
" print(tool.name)"
92185
]
93186
},
94187
{
95188
"cell_type": "markdown",
96189
"metadata": {},
97190
"source": [
98-
"## Example: Simple Agent"
191+
"The purpose of these tools is as follows:\n",
192+
"\n",
193+
"Each of these steps will be explained in great detail below.\n",
194+
"\n",
195+
"1. **Get Issues**- fetches issues from the repository.\n",
196+
"\n",
197+
"2. **Get Issue**- fetches details about a specific issue.\n",
198+
"\n",
199+
"3. **Comment on Issue**- posts a comment on a specific issue.\n",
200+
"\n",
201+
"4. **Create Pull Request**- creates a pull request from the bot's working branch to the base branch.\n",
202+
"\n",
203+
"5. **Create File**- creates a new file in the repository.\n",
204+
"\n",
205+
"6. **Read File**- reads a file from the repository.\n",
206+
"\n",
207+
"7. **Update File**- updates a file in the repository.\n",
208+
"\n",
209+
"8. **Delete File**- deletes a file from the repository."
210+
]
211+
},
212+
{
213+
"cell_type": "markdown",
214+
"metadata": {},
215+
"source": [
216+
"## Use within an agent"
99217
]
100218
},
101219
{
@@ -824,6 +942,15 @@
824942
"\n",
825943
"agent.run(prompt)"
826944
]
945+
},
946+
{
947+
"cell_type": "markdown",
948+
"metadata": {},
949+
"source": [
950+
"## API reference\n",
951+
"\n",
952+
"For detailed documentation of all `GithubToolkit` features and configurations head to the [API reference](https://api.python.langchain.com/en/latest/agent_toolkits/langchain_community.agent_toolkits.github.toolkit.GitHubToolkit.html)."
953+
]
827954
}
828955
],
829956
"metadata": {
@@ -842,7 +969,7 @@
842969
"name": "python",
843970
"nbconvert_exporter": "python",
844971
"pygments_lexer": "ipython3",
845-
"version": "3.10.13"
972+
"version": "3.10.4"
846973
}
847974
},
848975
"nbformat": 4,

0 commit comments

Comments
 (0)