chore: import upstream snapshot with attribution

2026-07-13 13:22:28 +08:00
commit c56bef871b
9296 changed files with 1854228 additions and 0 deletions
@@ -0,0 +1,113 @@
+---
+title: "GitHubFileEditorTool"
+id: githubfileeditortool
+slug: "/githubfileeditortool"
+description: "A Tool that allows Agents and ToolInvokers to edit files in GitHub repositories."
+---
+
+# GitHubFileEditorTool
+
+A Tool that allows Agents and ToolInvokers to edit files in GitHub repositories.
+
+<div className="key-value-table">
+
+|  |  |
+| --- | --- |
+| **Mandatory init variables** | `github_token`: GitHub personal access token. Can be set with `GITHUB_TOKEN` env var.    |
+| **API reference**            | [Tools](/reference/tools-api)                                                            |
+| **GitHub link**              | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github |
+
+</div>
+
+## Overview
+
+`GitHubFileEditorTool` wraps the [`GitHubFileEditor`](../../pipeline-components/connectors/githubfileeditor.mdx) component, providing a tool interface for use in agent workflows and tool-based pipelines.
+
+The tool supports multiple file operations including editing existing files, creating new files, deleting files, and undoing recent changes. It supports four main commands:
+
+- **EDIT**: Edit an existing file by replacing specific content
+- **CREATE**: Create a new file with specified content
+- **DELETE**: Delete an existing file
+- **UNDO**: Revert the last commit if made by the same user
+
+### Parameters
+
+- `name` is _optional_ and defaults to "file_editor". Specifies the name of the tool.
+- `description` is _optional_ and provides context to the LLM about what the tool does.
+- `github_token` is _mandatory_ and must be a GitHub personal access token for API authentication. The default setting uses the environment variable `GITHUB_TOKEN`.
+- `repo` is _optional_ and sets a default repository in owner/repo format.
+- `branch` is _optional_ and defaults to "main". Sets the default branch to work with.
+- `raise_on_failure` is _optional_ and defaults to `True`. If False, errors are returned instead of raising exceptions.
+
+## Usage
+
+Install the GitHub integration to use the `GitHubFileEditorTool`:
+
+```shell
+pip install github-haystack
+```
+
+:::info[Repository Placeholder]
+
+To run the following code snippets, you need to replace the `owner/repo` with your own GitHub repository name.
+:::
+
+### On its own
+
+Basic usage to edit a file:
+
+```python
+from haystack_integrations.tools.github import GitHubFileEditorTool
+
+tool = GitHubFileEditorTool()
+result = tool.invoke(
+    command="edit",
+    payload={
+        "path": "src/example.py",
+        "original": "def old_function():",
+        "replacement": "def new_function():",
+        "message": "Renamed function for clarity",
+    },
+    repo="owner/repo",
+    branch="main",
+)
+
+print(result)
+```
+
+```bash
+{'result': 'Edit successful'}
+```
+
+### With an Agent
+
+You can use `GitHubFileEditorTool` with the [Agent](../../pipeline-components/agents-1/agent.mdx) component. The Agent will automatically invoke the tool when needed to edit files in GitHub repositories.
+
+```python
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.components.agents import Agent
+from haystack_integrations.tools.github import GitHubFileEditorTool
+
+editor_tool = GitHubFileEditorTool(repo="owner/repo")
+
+agent = Agent(
+    chat_generator=OpenAIChatGenerator(),
+    tools=[editor_tool],
+    exit_conditions=["text"],
+)
+
+response = agent.run(
+    messages=[
+        ChatMessage.from_user(
+            "Edit the file README.md in the repository \"owner/repo\" and replace the original string 'tpyo' with the replacement 'typo'. This is all context you need.",
+        ),
+    ],
+)
+
+print(response["last_message"].text)
+```
+
+```bash
+The file `README.md` has been successfully edited to correct the spelling of 'tpyo' to 'typo'.
+```
@@ -0,0 +1,100 @@
+---
+title: "GitHubIssueCommenterTool"
+id: githubissuecommentertool
+slug: "/githubissuecommentertool"
+description: "A Tool that allows Agents and ToolInvokers to post comments to GitHub issues."
+---
+
+# GitHubIssueCommenterTool
+
+A Tool that allows Agents and ToolInvokers to post comments to GitHub issues.
+
+<div className="key-value-table">
+
+|  |  |
+| --- | --- |
+| **Mandatory init variables** | `github_token`: GitHub personal access token. Can be set with `GITHUB_TOKEN` env var.    |
+| **API reference**            | [Tools](/reference/tools-api)                                                            |
+| **GitHub link**              | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github |
+
+</div>
+
+## Overview
+
+`GitHubIssueCommenterTool` wraps the [`GitHubIssueCommenter`](../../pipeline-components/connectors/githubissuecommenter.mdx) component, providing a tool interface for use in agent workflows and tool-based pipelines.
+
+The tool takes a GitHub issue URL and comment text, then posts the comment to the specified issue using the GitHub API. This requires authentication since posting comments is an authenticated operation.
+
+### Parameters
+
+- `name` is _optional_ and defaults to "issue_commenter". Specifies the name of the tool.
+- `description` is _optional_ and provides context to the LLM about what the tool does.
+- `github_token` is _mandatory_ and must be a GitHub personal access token for API authentication. The default setting uses the environment variable `GITHUB_TOKEN`.
+- `raise_on_failure` is _optional_ and defaults to `True`. If False, errors are returned instead of raising exceptions.
+- `retry_attempts` is _optional_ and defaults to `2`. Number of retry attempts for failed requests.
+
+## Usage
+
+Install the GitHub integration to use the `GitHubIssueCommenterTool`:
+
+```shell
+pip install github-haystack
+```
+
+:::info[Repository Placeholder]
+
+To run the following code snippets, you need to replace the `owner/repo` with your own GitHub repository name.
+:::
+
+### On its own
+
+Basic usage to comment on an issue:
+
+```python
+from haystack_integrations.tools.github import GitHubIssueCommenterTool
+
+tool = GitHubIssueCommenterTool()
+result = tool.invoke(
+    url="https://github.com/owner/repo/issues/123",
+    comment="Thanks for reporting this issue! We'll look into it.",
+)
+
+print(result)
+```
+
+```bash
+{'success': True}
+```
+
+### With an Agent
+
+You can use `GitHubIssueCommenterTool` with the [Agent](../../pipeline-components/agents-1/agent.mdx) component. The Agent will automatically invoke the tool when needed to post comments on GitHub issues.
+
+```python
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.components.agents import Agent
+from haystack_integrations.tools.github import GitHubIssueCommenterTool
+
+comment_tool = GitHubIssueCommenterTool(name="github_issue_commenter")
+
+agent = Agent(
+    chat_generator=OpenAIChatGenerator(),
+    tools=[comment_tool],
+    exit_conditions=["text"],
+)
+
+response = agent.run(
+    messages=[
+        ChatMessage.from_user(
+            "Please post a helpful comment on this GitHub issue: https://github.com/owner/repo/issues/123 acknowledging the bug report and mentioning that we're investigating",
+        ),
+    ],
+)
+
+print(response["last_message"].text)
+```
+
+```bash
+I have posted the comment on the GitHub issue, acknowledging the bug report and mentioning that the team is investigating the problem. If you need anything else, feel free to ask!
+```
@@ -0,0 +1,108 @@
+---
+title: "GitHubIssueViewerTool"
+id: githubissueviewertool
+slug: "/githubissueviewertool"
+description: "A Tool that allows Agents and ToolInvokers to fetch and parse GitHub issues into documents."
+---
+
+# GitHubIssueViewerTool
+
+A Tool that allows Agents and ToolInvokers to fetch and parse GitHub issues into documents.
+
+<div className="key-value-table">
+
+|  |  |
+| --- | --- |
+| **API reference** | [Tools](/reference/tools-api)                                                            |
+| **GitHub link**   | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github |
+
+</div>
+
+## Overview
+
+`GitHubIssueViewerTool` wraps the [`GitHubIssueViewer`](../../pipeline-components/connectors/githubissueviewer.mdx) component, providing a tool interface for use in agent workflows and tool-based pipelines.
+
+The tool takes a GitHub issue URL and returns a list of documents where:
+
+- The first document contains the main issue content,
+- Subsequent documents contain the issue comments (if any).
+
+Each document includes rich metadata such as the issue title, number, state, creation date, author, and more.
+
+### Parameters
+
+- `name` is _optional_ and defaults to "issue_viewer". Specifies the name of the tool.
+- `description` is _optional_ and provides context to the LLM about what the tool does.
+- `github_token` is _optional_ but recommended for private repositories or to avoid rate limiting.
+- `raise_on_failure` is _optional_ and defaults to `True`. If False, errors are returned as documents instead of raising exceptions.
+- `retry_attempts` is _optional_ and defaults to `2`. Number of retry attempts for failed requests.
+
+## Usage
+
+Install the GitHub integration to use the `GitHubIssueViewerTool`:
+
+```shell
+pip install github-haystack
+```
+
+:::info[Repository Placeholder]
+
+To run the following code snippets, you need to replace the `owner/repo` with your own GitHub repository name.
+:::
+
+### On its own
+
+```python
+from haystack_integrations.tools.github import GitHubIssueViewerTool
+
+tool = GitHubIssueViewerTool()
+result = tool.invoke(url="https://github.com/deepset-ai/haystack/issues/123")
+
+print(result)
+```
+
+```bash
+{'documents': [Document(id=3989459bbd8c2a8420a9ba7f3cd3cf79bb41d78bd0738882e57d509e1293c67a, content: 'sentence-transformers = 0.2.6.1
+haystack = latest
+farm = 0.4.3 latest branch
+
+In the call to Emb...', meta: {'type': 'issue', 'title': 'SentenceTransformer no longer accepts \'gpu" as argument', 'number': 123, 'state': 'closed', 'created_at': '2020-05-28T04:49:31Z', 'updated_at': '2020-05-28T07:11:43Z', 'author': 'predoctech', 'url': 'https://github.com/deepset-ai/haystack/issues/123'}), Document(id=a8a56b9ad119244678804d5873b13da0784587773d8f839e07f644c4d02c167a, content: 'Thanks for reporting!
+Fixed with #124 ', meta: {'type': 'comment', 'issue_number': 123, 'created_at': '2020-05-28T07:11:42Z', 'updated_at': '2020-05-28T07:11:42Z', 'author': 'tholor', 'url': 'https://github.com/deepset-ai/haystack/issues/123#issuecomment-635153940'})]}
+```
+
+### With an Agent
+
+You can use `GitHubIssueViewerTool` with the [Agent](../../pipeline-components/agents-1/agent.mdx) component. The Agent will automatically invoke the tool when needed to fetch GitHub issue information.
+
+```python
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.components.agents import Agent
+from haystack_integrations.tools.github import GitHubIssueViewerTool
+
+issue_tool = GitHubIssueViewerTool(name="github_issue_viewer")
+
+agent = Agent(
+    chat_generator=OpenAIChatGenerator(),
+    tools=[issue_tool],
+    exit_conditions=["text"],
+)
+
+response = agent.run(
+    messages=[
+        ChatMessage.from_user(
+            "Please analyze this GitHub issue and summarize the main problem: https://github.com/deepset-ai/haystack/issues/123",
+        ),
+    ],
+)
+
+print(response["last_message"].text)
+```
+
+```bash
+The GitHub issue titled "SentenceTransformer no longer accepts 'gpu' as argument" (issue \#123) discusses a problem encountered when using the `EmbeddingRetriever()` function. The user reports that passing the argument `gpu=True` now causes an error because the method that processes this argument does not accept "gpu" anymore; instead, it previously accepted "cuda" without issues.
+
+The user indicates that this change is problematic since it prevents users from instantiating the embedding model with GPU support, forcing them to default to using only the CPU for model execution.
+
+The issue was later closed with a comment indicating it was fixed in another pull request (#124).
+```
@@ -0,0 +1,102 @@
+---
+title: "GitHubPRCreatorTool"
+id: githubprcreatortool
+slug: "/githubprcreatortool"
+description: "A Tool that allows Agents and ToolInvokers to create pull requests from a fork back to the original repository."
+---
+
+# GitHubPRCreatorTool
+
+A Tool that allows Agents and ToolInvokers to create pull requests from a fork back to the original repository.
+
+<div className="key-value-table">
+
+|  |  |
+| --- | --- |
+| **Mandatory init variables** | `github_token`: GitHub personal access token. Can be set with `GITHUB_TOKEN` env var.    |
+| **API reference**            | [Tools](/reference/tools-api)                                                            |
+| **GitHub link**              | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github |
+
+</div>
+
+## Overview
+
+`GitHubPRCreatorTool` wraps the [`GitHubPRCreator`](../../pipeline-components/connectors/githubprcreator.mdx) component, providing a tool interface for use in agent workflows and tool-based pipelines.
+
+The tool takes a GitHub issue URL and creates a pull request from your fork to the original repository, automatically linking it to the specified issue. It's designed to work with existing forks and assumes you have already made changes in a branch.
+
+### Parameters
+
+- `name` is _optional_ and defaults to "pr_creator". Specifies the name of the tool.
+- `description` is _optional_ and provides context to the LLM about what the tool does.
+- `github_token` is _mandatory_ and must be a GitHub personal access token from the fork owner. The default setting uses the environment variable `GITHUB_TOKEN`.
+- `raise_on_failure` is _optional_ and defaults to `True`. If False, errors are returned instead of raising exceptions.
+
+## Usage
+
+Install the GitHub integration to use the `GitHubPRCreatorTool`:
+
+```shell
+pip install github-haystack
+```
+
+:::info[Repository Placeholder]
+
+To run the following code snippets, you need to replace the `owner/repo` with your own GitHub repository name.
+:::
+
+### On its own
+
+Basic usage to create a pull request:
+
+```python
+from haystack_integrations.tools.github import GitHubPRCreatorTool
+
+tool = GitHubPRCreatorTool()
+result = tool.invoke(
+    issue_url="https://github.com/owner/repo/issues/123",
+    title="Fix issue #123",
+    body="This PR addresses issue #123 by implementing the requested changes.",
+    branch="fix-123",  # Branch in your fork with the changes
+    base="main",  # Branch in original repo to merge into
+)
+
+print(result)
+```
+
+```bash
+{'result': 'Pull request #16 created successfully and linked to issue #4'}
+```
+
+### With an Agent
+
+You can use `GitHubPRCreatorTool` with the [Agent](../../pipeline-components/agents-1/agent.mdx) component. The Agent will automatically invoke the tool when needed to create pull requests.
+
+```python
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.components.agents import Agent
+from haystack_integrations.tools.github import GitHubPRCreatorTool
+
+pr_tool = GitHubPRCreatorTool(name="github_pr_creator")
+
+agent = Agent(
+    chat_generator=OpenAIChatGenerator(),
+    tools=[pr_tool],
+    exit_conditions=["text"],
+)
+
+response = agent.run(
+    messages=[
+        ChatMessage.from_user(
+            "Create a pull request for issue https://github.com/owner/repo/issues/4 with title 'Fix authentication bug' and empty body using my fix-4 branch and main as target branch",
+        ),
+    ],
+)
+
+print(response["last_message"].text)
+```
+
+```bash
+The pull request titled "Fix authentication bug" has been created successfully and linked to issue [#123](https://github.com/owner/repo/issues/4).
+```
@@ -0,0 +1,136 @@
+---
+title: "GitHubRepoViewerTool"
+id: githubrepoviewertool
+slug: "/githubrepoviewertool"
+description: "A Tool that allows Agents and ToolInvokers to navigate and fetch content from GitHub repositories."
+---
+
+# GitHubRepoViewerTool
+
+A Tool that allows Agents and ToolInvokers to navigate and fetch content from GitHub repositories.
+
+<div className="key-value-table">
+
+|  |  |
+| --- | --- |
+| **API reference** | [Tools](/reference/tools-api)                                                            |
+| **GitHub link**   | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/github |
+
+</div>
+
+## Overview
+
+`GitHubRepoViewerTool` wraps the [`GitHubRepoViewer`](../../pipeline-components/connectors/githubrepoviewer.mdx) component, providing a tool interface for use in agent workflows and tool-based pipelines.
+
+The tool provides different behavior based on the path type:
+
+- **For directories**: Returns a list of documents, one for each item (files and subdirectories),
+- **For files**: Returns a single document containing the file content.
+
+Each document includes rich metadata such as the path, type, size, and URL.
+
+### Parameters
+
+- `name` is _optional_ and defaults to "repo_viewer". Specifies the name of the tool.
+- `description` is _optional_ and provides context to the LLM about what the tool does.
+- `github_token` is _optional_ but recommended for private repositories or to avoid rate limiting.
+- `repo` is _optional_ and sets a default repository in owner/repo format.
+- `branch` is _optional_ and defaults to "main". Sets the default branch to work with.
+- `raise_on_failure` is _optional_ and defaults to `True`. If False, errors are returned as documents instead of raising exceptions.
+- `max_file_size` is _optional_ and defaults to `1,000,000` bytes (1MB). Maximum file size to fetch.
+
+## Usage
+
+Install the GitHub integration to use the `GitHubRepoViewerTool`:
+
+```shell
+pip install github-haystack
+```
+
+:::info[Repository Placeholder]
+
+To run the following code snippets, you need to replace the `owner/repo` with your own GitHub repository name.
+:::
+
+### On its own
+
+Basic usage to view repository contents:
+
+```python
+from haystack_integrations.tools.github import GitHubRepoViewerTool
+
+tool = GitHubRepoViewerTool()
+result = tool.invoke(
+    repo="deepset-ai/haystack",
+    path="haystack/components",
+    branch="main",
+)
+
+print(result)
+```
+
+```bash
+{'documents': [Document(id=..., content: 'agents', meta: {'path': 'haystack/components/agents', 'type': 'dir', 'size': 0, 'url': 'https://github.com/deepset-ai/haystack/tree/main/haystack/components/agents'}), Document(id=..., content: 'audio', meta: {'path': 'haystack/components/audio', 'type': 'dir', 'size': 0, 'url': 'https://github.com/deepset-ai/haystack/tree/main/haystack/components/audio'}),...]}
+```
+
+### With an Agent
+
+You can use `GitHubRepoViewerTool` with the [Agent](../../pipeline-components/agents-1/agent.mdx) component. The Agent will automatically invoke the tool when needed to explore repository structure and read files.
+
+Note that we set the Agent's `state_schema` parameter in this code example so that the GitHubRepoViewerTool can write documents to the state.
+
+```python
+from typing import List
+
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage, Document
+from haystack.components.agents import Agent
+from haystack_integrations.tools.github import GitHubRepoViewerTool
+
+repo_tool = GitHubRepoViewerTool(name="github_repo_viewer")
+
+agent = Agent(
+    chat_generator=OpenAIChatGenerator(),
+    tools=[repo_tool],
+    exit_conditions=["text"],
+    state_schema={"documents": {"type": List[Document]}},
+)
+
+response = agent.run(
+    messages=[
+        ChatMessage.from_user(
+            "Can you analyze the structure of the deepset-ai/haystack repository and tell me about the main components?",
+        ),
+    ],
+)
+
+print(response["last_message"].text)
+```
+
+```bash
+The `deepset-ai/haystack` repository has a structured layout that includes several important components. Here's an overview of its main parts:
+
+1. **Directories**:
+   - **`.github`**: Contains GitHub-specific configuration files and workflows.
+   - **`docker`**: Likely includes Docker-related files for containerization of the Haystack application.
+   - **`docs`**: Contains documentation for the Haystack project. This could include guides, API documentation, and other related resources.
+   - **`e2e`**: This likely stands for "end-to-end", possibly containing tests or examples related to end-to-end functionality of the Haystack framework.
+   - **`examples`**: Includes example scripts or notebooks demonstrating how to use Haystack.
+   - **`haystack`**: This is likely the core source code of the Haystack framework itself, containing the main functionality and classes.
+   - **`proposals`**: A directory that may contain proposals for new features or changes to the Haystack project.
+   - **`releasenotes`**: Contains notes about various releases, including changes and improvements.
+   - **`test`**: This directory likely contains unit tests and other testing utilities to ensure code quality and functionality.
+
+2. **Files**:
+   - **`.gitignore`**: Specifies files and directories that should be ignored by Git.
+   - **`.pre-commit-config.yaml`**: Configuration file for pre-commit hooks to automate code quality checks.
+   - **`CITATION.cff`**: Might include information on how to cite the repository in academic work.
+   - **`code_of_conduct.txt`**: Contains the code of conduct for contributors and users of the repository.
+   - **`CONTRIBUTING.md`**: Guidelines for contributing to the repository.
+   - **`LICENSE`**: The license under which the project is distributed.
+   - **`VERSION.txt`**: Contains versioning information for the project.
+   - **`README.md`**: A markdown file that usually provides an overview of the project, installation instructions, and usage examples.
+   - **`SECURITY.md`**: Contains information about the security policy of the repository.
+
+This structure indicates a well-organized repository that follows common conventions in open-source projects, with a focus on documentation, contribution guidelines, and testing. The core functionalities are likely housed in the `haystack` directory, with additional resources provided in the other directories.
+```