Metadata-Version: 2.5
Name: langchain-github
Version: 0.2.0
Summary: LangChain retrievers and loaders for GitHub repos, issues and discussions
Project-URL: Homepage, https://github.com/daivikawasthi01/langchain-github
Project-URL: Repository, https://github.com/daivikawasthi01/langchain-github
Project-URL: Issues, https://github.com/daivikawasthi01/langchain-github/issues
Author-email: Daivik Awasthi <daivikawasthi.01@gmail.com>
License: MIT
License-File: LICENSE
Keywords: document-loader,github,langchain,llm,rag,retriever
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: langchain-core>=0.3.0
Requires-Dist: langchain-text-splitters>=0.3.0
Requires-Dist: pydantic>=2.5
Requires-Dist: typing-extensions>=4.5
Provides-Extra: dev
Requires-Dist: langchain-tests>=0.3; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-recording>=0.13; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# langchain-github

LangChain retrievers and loaders for GitHub repositories, issues and discussions.

- **`GitHubRepoRetriever`**: ask a question about a repo and get the best code and doc passages, each with a permalink to the exact commit and lines. Works on any branch, tag or commit.
- **`GitHubIssuesRetriever`**: describe a problem or paste a traceback and get the matching issue, discussion or comment, with how it was resolved (`fixed`, `answered`, `closed`, `wontfix`, `duplicate`, `open`) and the PR that closed it.
- **`GitHubRepositoryLoader`**, **`GitHubIssuesLoader`**: the same data as plain `Document`s.

## Installation

```bash
pip install langchain-github
```

No token is needed to try it, but without signing in GitHub allows only 60 requests an hour. To sign in once, install the [GitHub CLI](https://cli.github.com) and run:

```bash
gh auth login
```

The package picks up that login automatically. It also reads `GITHUB_TOKEN` or `GH_TOKEN`, or you can pass `token=`. Public repos need no special permissions.

## Usage

```python
from langchain_github import GitHubRepoRetriever, GitHubIssuesRetriever

docs = GitHubRepoRetriever(repo="pallets/click", k=3).invoke(
    "how are environment variables read for options?"
)
print(docs[0].metadata["url"])  # https://github.com/pallets/click/blob/<sha>/docs/options.md#L677-L690

issues = GitHubIssuesRetriever(repo="psf/requests").invoke("requests hang when all sockets are in use")
m = issues[0].metadata
print(m["title"], m["resolution"], m["resolved_by_urls"], m["url"])
```

Both retrievers support `ainvoke`, and `k` can be set on the retriever or per call. Use `with GitHubRepoRetriever(...) as retriever:` (or call `retriever.close()`) to close connections when you are done.

## Use with a chat model

```python
from langchain.chat_models import init_chat_model
from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough

retriever = GitHubRepoRetriever(repo="pallets/click", k=4)
prompt = ChatPromptTemplate.from_messages([
    ("system", "Answer from these passages and cite their links.\n\n{context}"),
    ("human", "{question}"),
])
format_docs = lambda docs: "\n\n".join(f"[{d.metadata['url']}]\n{d.page_content}" for d in docs)

chain = (
    {"context": retriever | format_docs, "question": RunnablePassthrough()}
    | prompt | init_chat_model("anthropic:claude-sonnet-5-5") | StrOutputParser()
)
print(chain.invoke("how are environment variables read for options?"))
```

## Key options

| Option | Effect | Example | What the example does |
|---|---|---|---|
| `ref=` | Branch, tag or commit (repo retriever). | `GitHubRepoRetriever(repo="pallets/click", ref="8.1.7")` | Searches the code as it was at release 8.1.7, not the latest version. Links point to that exact commit. |
| `embeddings=` | Any LangChain `Embeddings`; turns on hybrid ranking. Recommended for natural-language questions. | `GitHubRepoRetriever(repo="pallets/click", embeddings=Fast())` (`Fast` is defined below) | Matches on meaning as well as words, so "env vars" also finds text about "environment variables". |
| `cache_dir=` | Cache downloads (and embeddings, if used) so a new commit refetches only changed files and a restart is fast. | `GitHubRepoRetriever(repo="pallets/click", cache_dir=".cache/gh")` | Saves downloaded files in `.cache/gh`. The next run reuses them and only fetches what changed. |
| `include` / `exclude` / `extensions` | Filter files with gitignore-style globs. | `GitHubRepoRetriever(repo="pallets/click", include=["docs/**"], extensions=[".md"])` | Only searches Markdown files under `docs/`, so code and tests never show up in results. |
| `mode=` | Issues retriever: `index`, `search` or `auto` (default). | `GitHubIssuesRetriever(repo="pallets/click", mode="search")` | Asks GitHub's own search for candidate issues instead of downloading every issue first. |

Requests stay within GitHub's limits: 60 per hour when you are not signed in and 5,000 per hour when you are (run `gh auth login` once to sign in). Searches are paced at 30 per minute, and meaning-based (hybrid) issue searches at 10 per minute. If GitHub asks to slow down, the package waits and retries.

`embeddings=` takes an object, not a string. This free one runs on your machine (`pip install fastembed`), and any other LangChain embeddings class, such as `OpenAIEmbeddings()`, works the same way:

```python
from fastembed import TextEmbedding
from langchain_core.embeddings import Embeddings

class Fast(Embeddings):
    def __init__(self):
        self.model = TextEmbedding("BAAI/bge-small-en-v1.5")  # small model, downloaded once
    def embed_documents(self, texts):
        return [v.tolist() for v in self.model.embed(texts)]
    def embed_query(self, text):
        return next(iter(self.model.embed([text]))).tolist()
```

The first query builds the index, which takes a couple of minutes on a laptop for a repo like click. Later queries are fast. With `cache_dir=` that work is saved, so the next run does not repeat it.

## How well does it work?

- **Repos:** finds the right passages noticeably better than plain keyword search, and about as well as a standard vector store, while also giving you exact line links, any branch or tag, and quick updates when the repo changes.
- **Issues:** about as good as GitHub's own search at finding the right issue, and it adds what search does not: discussions, the closing pull request, and whether the problem was fixed, answered or closed as a duplicate.
- **Wording matters:** by default it matches words, so it works best when your question uses the project's own terms. For casual or paraphrased questions, pass `embeddings=` so it also matches meaning.

## Limits

- Read-only. Private repositories need a token that can read them.
- Discussions are only included when you are signed in, because GitHub does not serve them to anonymous users. Run `gh auth login` once to enable them.
- GitHub search caps at 1,000 results. Very large monorepos are capped by `max_archive_mb`.
- The index is held in memory per retriever instance.
- Not an official GitHub product.

## Development

```bash
pip install -e '.[dev]' && pytest              # offline tests
GITHUB_LIVE=1 GITHUB_TOKEN=... pytest -m live  # live tests
```

MIT licensed. 
Issues and pull requests welcome at [github.com/daivikawasthi01/langchain-github](https://github.com/daivikawasthi01/langchain-github).
