Metadata-Version: 2.5
Name: langchain-youtube
Version: 0.2.0
Summary: LangChain retriever integration for YouTube — search videos, fetch playlists, extract transcripts, retrieve video metadata, and fetch comments.
Project-URL: Homepage, https://github.com/urraf/langchain-youtube
Project-URL: Repository, https://github.com/urraf/langchain-youtube
Project-URL: Documentation, https://github.com/urraf/langchain-youtube#readme
Project-URL: Bug Tracker, https://github.com/urraf/langchain-youtube/issues
Author: Farhan
License-Expression: MIT
License-File: LICENSE
Keywords: ai,langchain,llm,rag,retriever,transcript,youtube
Classifier: Development Status :: 4 - Beta
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: google-api-python-client>=2.0.0
Requires-Dist: langchain-core>=0.2.0
Requires-Dist: youtube-transcript-api>=0.6.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# 🎬 langchain-youtube

[![PyPI version](https://badge.fury.io/py/langchain-youtube.svg)](https://badge.fury.io/py/langchain-youtube)
[![CI](https://github.com/urraf/langchain-youtube/actions/workflows/ci.yml/badge.svg)](https://github.com/urraf/langchain-youtube/actions)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**LangChain retrievers for YouTube** — search videos, fetch playlists, extract transcripts, and retrieve video metadata as LangChain `Document` objects.

Perfect for building RAG applications, video summarizers, and AI-powered YouTube tools.

## ✨ Features

| Retriever | What it does | API Key Required? |
|---|---|---|
| `YouTubeSearchRetriever` | Search videos by keyword | ✅ Yes |
| `YouTubePlaylistRetriever` | Fetch all videos from a playlist | ✅ Yes |
| `YouTubeTranscriptRetriever` | Extract video transcripts/captions | ❌ No! |
| `YouTubeVideoRetriever` | Get detailed video metadata | ✅ Yes |

## 📦 Installation

```bash
pip install langchain-youtube
```

## 🔑 Setup (for API key features)

1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
2. Create a project and enable the [YouTube Data API v3](https://console.cloud.google.com/apis/library/youtube.googleapis.com)
3. Create an API key under **Credentials**

> **Note:** The `YouTubeTranscriptRetriever` does NOT need an API key!

## 🚀 Quick Start

### Search YouTube Videos

```python
from langchain_youtube import YouTubeSearchRetriever

retriever = YouTubeSearchRetriever(
    api_key="YOUR_API_KEY",
    max_results=5,
    order="relevance",  # or "date", "viewCount", "rating"
)

docs = retriever.invoke("LangChain RAG tutorial")

for doc in docs:
    print(f"📹 {doc.metadata['url']}")
    print(f"   {doc.page_content[:100]}...")
    print(f"   👁 {doc.metadata['view_count']:,} views")
```

### Extract Video Transcripts (No API Key!)

```python
from langchain_youtube import YouTubeTranscriptRetriever

retriever = YouTubeTranscriptRetriever(
    languages=["en", "es"],  # Preferred languages
    chunk_size=3000,          # Split long transcripts for LLM context limits
)

docs = retriever.invoke("https://www.youtube.com/watch?v=VIDEO_ID")

for doc in docs:
    print(f"📝 Chunk {doc.metadata['chunk_index'] + 1}/{doc.metadata['total_chunks']}")
    print(doc.page_content[:200])
```

### Fetch Playlist Videos

```python
from langchain_youtube import YouTubePlaylistRetriever

retriever = YouTubePlaylistRetriever(
    api_key="YOUR_API_KEY",
    playlist_url="https://www.youtube.com/playlist?list=PLxxxxxx",
    max_results=100,
)

docs = retriever.invoke("fetch")  # Query is unused for playlists

for doc in docs:
    print(f"#{doc.metadata['position']} — {doc.page_content[:80]}")
```

### Get Video Metadata

```python
from langchain_youtube import YouTubeVideoRetriever

retriever = YouTubeVideoRetriever(api_key="YOUR_API_KEY")

docs = retriever.invoke("https://www.youtube.com/watch?v=dQw4w9WgXcQ")

video = docs[0]
print(f"Title: {video.page_content}")
print(f"Views: {video.metadata['view_count']:,}")
print(f"Likes: {video.metadata['like_count']:,}")
print(f"Duration: {video.metadata['duration']}")
```

## 🔗 Use with LangChain Chains

```python
from langchain_youtube import YouTubeTranscriptRetriever
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

# Set up retriever and LLM
retriever = YouTubeTranscriptRetriever(languages=["en"])
llm = ChatOpenAI(model="gpt-4o-mini")

prompt = ChatPromptTemplate.from_template(
    "Summarize this YouTube video transcript in 5 bullet points:\n\n{context}"
)

# Build a simple chain
chain = (
    {"context": retriever}
    | prompt
    | llm
    | StrOutputParser()
)

summary = chain.invoke("https://www.youtube.com/watch?v=VIDEO_ID")
print(summary)
```

## 🧪 Development

```bash
# Clone the repo
git clone https://github.com/urraf/langchain-youtube.git
cd langchain-youtube

# Install in dev mode
pip install -e ".[dev]"

# Run unit tests (no API key needed)
pytest tests/unit_tests/ -v

# Run integration tests (requires API key)
YOUTUBE_API_KEY=your_key pytest tests/integration_tests/ -v

# Lint
ruff check src/ tests/
```

## 📄 License

MIT — see [LICENSE](LICENSE) for details.
