langchain-getyoutubetranscript 0.1.0__tar.gz

langchain_getyoutubetranscript-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+dist/
+__pycache__/
+*.egg-info/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/

langchain_getyoutubetranscript-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tubeagentkit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

langchain_getyoutubetranscript-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.5
+Name: langchain-getyoutubetranscript
+Version: 0.1.0
+Summary: YouTube transcript tools and document loader for LangChain: get YouTube video transcripts with timestamps and search YouTube from agents and RAG pipelines, via the GetYouTubeTranscript API.
+Project-URL: Homepage, https://getyoutubetranscript.com
+Project-URL: Documentation, https://github.com/tubeagentkit/langchain-getyoutubetranscript#readme
+Project-URL: Repository, https://github.com/tubeagentkit/langchain-getyoutubetranscript
+Project-URL: API reference, https://getyoutubetranscript.com/docs
+Project-URL: Get an API key, https://getyoutubetranscript.com/dashboard
+Author: tubeagentkit
+License: MIT
+License-File: LICENSE
+Keywords: agents,captions,document-loader,langchain,llm,rag,subtitles,tools,transcript,youtube,youtube-transcript
+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 :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: getyoutubetranscript<1.0.0,>=0.3.0
+Requires-Dist: langchain-core<2.0.0,>=0.3.0
+Provides-Extra: test
+Requires-Dist: langchain-tests>=0.3.0; extra == 'test'
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# langchain-getyoutubetranscript
+
+YouTube transcript tools and a document loader for [LangChain](https://www.langchain.com), powered by the [GetYouTubeTranscript](https://getyoutubetranscript.com) API. Give agents the transcript of any YouTube video (optionally with `[m:ss]` timestamps) and YouTube search, or load transcripts into RAG pipelines.
+
+The API fetches transcripts on its own servers, so it works from cloud servers and serverless functions without proxies, and without `RequestBlocked` / `IpBlocked` errors.
+
+## Install
+
+```bash
+pip install langchain-getyoutubetranscript
+```
+
+Get an API key at [getyoutubetranscript.com/dashboard](https://getyoutubetranscript.com/dashboard) (free tier included) and set it:
+
+```bash
+export GETYOUTUBETRANSCRIPT_API_KEY=sk_live_...
+```
+
+Or pass `api_key="..."` to any class.
+
+## Tools
+
+| Class | Tool name | What it does |
+| --- | --- | --- |
+| `GetYouTubeTranscriptTool` | `youtube_transcript` | Transcript of a video (URL or ID) with title and channel. `timestamps=True` prefixes each line with `[m:ss]`. |
+| `GetYouTubeTranscriptSearchTool` | `youtube_search` | Search YouTube for videos or channels. Returns JSON with a `continuation_token` for the next page. |
+
+```python
+from langchain_getyoutubetranscript import GetYouTubeTranscriptTool
+
+tool = GetYouTubeTranscriptTool()
+print(tool.invoke({"video": "https://youtu.be/jNQXAC9IVRw", "timestamps": True}))
+# Title: Me at the zoo
+# Channel: jawed
+# Language: en
+#
+# [0:01] All right, so here we are, in front of the elephants
+# ...
+```
+
+API errors (no captions, invalid video, out of credits) come back to the agent as a short message instead of raising.
+
+### With an agent
+
+```python
+from langchain.agents import create_agent
+from langchain_getyoutubetranscript import GetYouTubeTranscriptSearchTool, GetYouTubeTranscriptTool
+
+agent = create_agent(
+    model="anthropic:claude-sonnet-4-5",
+    tools=[GetYouTubeTranscriptSearchTool(), GetYouTubeTranscriptTool()],
+)
+agent.invoke(
+    {"messages": [{"role": "user", "content": "Find a short talk on transformers and summarize it with timestamps."}]}
+)
+```
+
+## Document loader
+
+```python
+from langchain_getyoutubetranscript import GetYouTubeTranscriptLoader
+
+docs = GetYouTubeTranscriptLoader(
+    ["https://youtu.be/jNQXAC9IVRw", "5e37ZT3SQbk"],
+    language="en",
+    timestamps=False,
+).load()
+
+print(docs[0].metadata)
+# {'source': 'https://www.youtube.com/watch?v=jNQXAC9IVRw', 'video_id': 'jNQXAC9IVRw',
+#  'title': 'Me at the zoo', 'author_name': 'jawed', 'language_code': 'en', 'word_count': 39}
+```
+
+One `Document` per video. With `timestamps=True`, `page_content` is `[m:ss]` lines and `metadata["segments"]` holds `{start, duration, text}` per caption line (seconds).
+
+## Pricing
+
+Each transcript or search request uses one credit from your GetYouTubeTranscript account. Failed requests are not charged.
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest                                        # unit + LangChain standard tests, no network
+GETYOUTUBETRANSCRIPT_API_KEY=... pytest tests/integration_tests   # live, spends credits
+```
+
+## Links
+
+- [GetYouTubeTranscript API docs](https://getyoutubetranscript.com/docs)
+- [Python SDK](https://pypi.org/project/getyoutubetranscript/) (this package is built on it)
+- [License: MIT](LICENSE)

langchain_getyoutubetranscript-0.1.0/README.md

@@ -0,0 +1,92 @@
+# langchain-getyoutubetranscript
+
+YouTube transcript tools and a document loader for [LangChain](https://www.langchain.com), powered by the [GetYouTubeTranscript](https://getyoutubetranscript.com) API. Give agents the transcript of any YouTube video (optionally with `[m:ss]` timestamps) and YouTube search, or load transcripts into RAG pipelines.
+
+The API fetches transcripts on its own servers, so it works from cloud servers and serverless functions without proxies, and without `RequestBlocked` / `IpBlocked` errors.
+
+## Install
+
+```bash
+pip install langchain-getyoutubetranscript
+```
+
+Get an API key at [getyoutubetranscript.com/dashboard](https://getyoutubetranscript.com/dashboard) (free tier included) and set it:
+
+```bash
+export GETYOUTUBETRANSCRIPT_API_KEY=sk_live_...
+```
+
+Or pass `api_key="..."` to any class.
+
+## Tools
+
+| Class | Tool name | What it does |
+| --- | --- | --- |
+| `GetYouTubeTranscriptTool` | `youtube_transcript` | Transcript of a video (URL or ID) with title and channel. `timestamps=True` prefixes each line with `[m:ss]`. |
+| `GetYouTubeTranscriptSearchTool` | `youtube_search` | Search YouTube for videos or channels. Returns JSON with a `continuation_token` for the next page. |
+
+```python
+from langchain_getyoutubetranscript import GetYouTubeTranscriptTool
+
+tool = GetYouTubeTranscriptTool()
+print(tool.invoke({"video": "https://youtu.be/jNQXAC9IVRw", "timestamps": True}))
+# Title: Me at the zoo
+# Channel: jawed
+# Language: en
+#
+# [0:01] All right, so here we are, in front of the elephants
+# ...
+```
+
+API errors (no captions, invalid video, out of credits) come back to the agent as a short message instead of raising.
+
+### With an agent
+
+```python
+from langchain.agents import create_agent
+from langchain_getyoutubetranscript import GetYouTubeTranscriptSearchTool, GetYouTubeTranscriptTool
+
+agent = create_agent(
+    model="anthropic:claude-sonnet-4-5",
+    tools=[GetYouTubeTranscriptSearchTool(), GetYouTubeTranscriptTool()],
+)
+agent.invoke(
+    {"messages": [{"role": "user", "content": "Find a short talk on transformers and summarize it with timestamps."}]}
+)
+```
+
+## Document loader
+
+```python
+from langchain_getyoutubetranscript import GetYouTubeTranscriptLoader
+
+docs = GetYouTubeTranscriptLoader(
+    ["https://youtu.be/jNQXAC9IVRw", "5e37ZT3SQbk"],
+    language="en",
+    timestamps=False,
+).load()
+
+print(docs[0].metadata)
+# {'source': 'https://www.youtube.com/watch?v=jNQXAC9IVRw', 'video_id': 'jNQXAC9IVRw',
+#  'title': 'Me at the zoo', 'author_name': 'jawed', 'language_code': 'en', 'word_count': 39}
+```
+
+One `Document` per video. With `timestamps=True`, `page_content` is `[m:ss]` lines and `metadata["segments"]` holds `{start, duration, text}` per caption line (seconds).
+
+## Pricing
+
+Each transcript or search request uses one credit from your GetYouTubeTranscript account. Failed requests are not charged.
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest                                        # unit + LangChain standard tests, no network
+GETYOUTUBETRANSCRIPT_API_KEY=... pytest tests/integration_tests   # live, spends credits
+```
+
+## Links
+
+- [GetYouTubeTranscript API docs](https://getyoutubetranscript.com/docs)
+- [Python SDK](https://pypi.org/project/getyoutubetranscript/) (this package is built on it)
+- [License: MIT](LICENSE)

langchain_getyoutubetranscript-0.1.0/langchain_getyoutubetranscript/__init__.py

@@ -0,0 +1,6 @@
+"""LangChain integration for the GetYouTubeTranscript API: YouTube transcripts and search."""
+
+from langchain_getyoutubetranscript.document_loaders import GetYouTubeTranscriptLoader
+from langchain_getyoutubetranscript.tools import GetYouTubeTranscriptSearchTool, GetYouTubeTranscriptTool
+
+__all__ = ["GetYouTubeTranscriptLoader", "GetYouTubeTranscriptSearchTool", "GetYouTubeTranscriptTool"]

langchain_getyoutubetranscript-0.1.0/langchain_getyoutubetranscript/_client.py

@@ -0,0 +1,27 @@
+"""Shared API key handling for the tools and the loader."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from getyoutubetranscript import Client, to_timed_text
+from pydantic import SecretStr
+
+API_KEY_ENV = "GETYOUTUBETRANSCRIPT_API_KEY"
+
+
+def make_client(api_key: SecretStr | None) -> Client:
+    if api_key is None or not api_key.get_secret_value():
+        raise ValueError(
+            f"A GetYouTubeTranscript API key is required. Pass api_key=... or set {API_KEY_ENV}. "
+            "Get one at https://getyoutubetranscript.com/dashboard"
+        )
+    return Client(api_key=api_key.get_secret_value())
+
+
+def format_transcript(result: Mapping[str, Any], timestamps: bool) -> str:
+    """Title and channel header, then the transcript (``[m:ss]`` lines when timestamps)."""
+    body = to_timed_text(result) if timestamps and result.get("segments") else result.get("transcript", "")
+    header = f"Title: {result.get('title', '')}\nChannel: {result.get('author_name', '')}\nLanguage: {result.get('language_code', '')}"
+    return f"{header}\n\n{body}"

langchain_getyoutubetranscript-0.1.0/langchain_getyoutubetranscript/document_loaders.py

@@ -0,0 +1,58 @@
+"""Load YouTube transcripts as LangChain Documents."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Sequence
+
+from getyoutubetranscript import to_timed_text
+from langchain_core.document_loaders import BaseLoader
+from langchain_core.documents import Document
+from langchain_core.utils import secret_from_env
+from pydantic import SecretStr
+
+from ._client import API_KEY_ENV, make_client
+
+
+class GetYouTubeTranscriptLoader(BaseLoader):
+    """Load the transcripts of one or more YouTube videos, one Document per video.
+
+    .. code-block:: python
+
+        from langchain_getyoutubetranscript import GetYouTubeTranscriptLoader
+
+        docs = GetYouTubeTranscriptLoader(["https://youtu.be/jNQXAC9IVRw"]).load()
+
+    ``page_content`` is the transcript text (``[m:ss]`` lines when ``timestamps=True``).
+    ``metadata`` has ``source``, ``video_id``, ``title``, ``author_name``,
+    ``language_code`` and ``word_count``, plus ``segments`` when ``timestamps=True``.
+    """
+
+    def __init__(
+        self,
+        videos: str | Sequence[str],
+        *,
+        language: str | None = None,
+        timestamps: bool = False,
+        api_key: str | None = None,
+    ) -> None:
+        self.videos = [videos] if isinstance(videos, str) else list(videos)
+        self.language = language
+        self.timestamps = timestamps
+        key = SecretStr(api_key) if api_key else secret_from_env(API_KEY_ENV, default=None)()
+        self._client = make_client(key)
+
+    def lazy_load(self) -> Iterator[Document]:
+        for video in self.videos:
+            result = self._client.get_transcript(video, language=self.language, timestamps=self.timestamps)
+            text = to_timed_text(result) if self.timestamps and result.get("segments") else result.get("transcript", "")
+            metadata = {
+                "source": f"https://www.youtube.com/watch?v={result['video_id']}",
+                "video_id": result["video_id"],
+                "title": result.get("title", ""),
+                "author_name": result.get("author_name", ""),
+                "language_code": result.get("language_code", ""),
+                "word_count": result.get("word_count", 0),
+            }
+            if self.timestamps and result.get("segments"):
+                metadata["segments"] = result["segments"]
+            yield Document(page_content=text, metadata=metadata)

langchain_getyoutubetranscript-0.1.0/langchain_getyoutubetranscript/tools.py

@@ -0,0 +1,97 @@
+"""LangChain tools for the GetYouTubeTranscript API."""
+
+from __future__ import annotations
+
+import json
+from typing import Literal
+
+from getyoutubetranscript import Client, GetYouTubeTranscriptError
+from langchain_core.tools import BaseTool, ToolException
+from langchain_core.utils import secret_from_env
+from pydantic import BaseModel, Field, PrivateAttr, SecretStr
+
+from ._client import API_KEY_ENV, format_transcript, make_client
+
+
+class _ApiKeyMixin(BaseModel):
+    api_key: SecretStr | None = Field(default_factory=secret_from_env(API_KEY_ENV, default=None))
+    """GetYouTubeTranscript API key. Defaults to the ``GETYOUTUBETRANSCRIPT_API_KEY`` env var."""
+
+    _client: Client | None = PrivateAttr(default=None)
+
+    @property
+    def client(self) -> Client:
+        if self._client is None:
+            self._client = make_client(self.api_key)
+        return self._client
+
+
+class TranscriptInput(BaseModel):
+    video: str = Field(description="YouTube video URL (watch, youtu.be, Shorts or live) or the 11-character video ID.")
+    language: str | None = Field(default=None, description="Optional caption language code, e.g. 'en' or 'es'.")
+    timestamps: bool = Field(
+        default=False,
+        description="Set to true to prefix each caption line with its start time, e.g. [1:05], for quoting or linking moments.",
+    )
+
+
+class GetYouTubeTranscriptTool(_ApiKeyMixin, BaseTool):  # type: ignore[override]
+    """Get the transcript of a YouTube video.
+
+    Setup:
+        ``pip install langchain-getyoutubetranscript`` and set ``GETYOUTUBETRANSCRIPT_API_KEY``.
+
+    Invoke:
+        .. code-block:: python
+
+            tool = GetYouTubeTranscriptTool()
+            tool.invoke({"video": "https://youtu.be/jNQXAC9IVRw", "timestamps": True})
+    """
+
+    name: str = "youtube_transcript"
+    description: str = (
+        "Get the transcript (spoken text) of a YouTube video from its URL or video ID, with the title and channel. "
+        "Use it to summarize, quote or answer questions about a video."
+    )
+    args_schema: type[BaseModel] = TranscriptInput
+    handle_tool_error: bool = True
+
+    def _run(self, video: str, language: str | None = None, timestamps: bool = False, **kwargs: object) -> str:
+        try:
+            result = self.client.get_transcript(video, language=language, timestamps=timestamps)
+        except GetYouTubeTranscriptError as e:
+            raise ToolException(e.message) from e
+        return format_transcript(result, timestamps)
+
+
+class SearchInput(BaseModel):
+    query: str = Field(description="What to search YouTube for.")
+    type: Literal["video", "channel"] = Field(default="video", description="Search for videos or channels.")
+    page_token: str | None = Field(
+        default=None, description="continuation_token from a previous search result, to get the next page."
+    )
+
+
+class GetYouTubeTranscriptSearchTool(_ApiKeyMixin, BaseTool):  # type: ignore[override]
+    """Search YouTube for videos or channels.
+
+    Invoke:
+        .. code-block:: python
+
+            GetYouTubeTranscriptSearchTool().invoke({"query": "linear algebra lecture"})
+    """
+
+    name: str = "youtube_search"
+    description: str = (
+        "Search YouTube for videos or channels. Returns JSON with titles, video or channel IDs, links, channel, "
+        "views, length and upload date, plus a continuation_token for the next page."
+    )
+    args_schema: type[BaseModel] = SearchInput
+    handle_tool_error: bool = True
+
+    def _run(self, query: str, type: str = "video", page_token: str | None = None, **kwargs: object) -> str:
+        try:
+            result = self.client.search(query, type=type, page_token=page_token)
+        except GetYouTubeTranscriptError as e:
+            raise ToolException(e.message) from e
+        return json.dumps(result, ensure_ascii=False)

langchain_getyoutubetranscript-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-getyoutubetranscript"
+version = "0.1.0"
+description = "YouTube transcript tools and document loader for LangChain: get YouTube video transcripts with timestamps and search YouTube from agents and RAG pipelines, via the GetYouTubeTranscript API."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "tubeagentkit" }]
+keywords = ["langchain", "youtube", "youtube-transcript", "transcript", "captions", "subtitles", "agents", "rag", "llm", "tools", "document-loader"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Multimedia :: Video",
+]
+dependencies = [
+    "langchain-core>=0.3.0,<2.0.0",
+    "getyoutubetranscript>=0.3.0,<1.0.0",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7.0", "langchain-tests>=0.3.0"]
+
+[project.urls]
+Homepage = "https://getyoutubetranscript.com"
+Documentation = "https://github.com/tubeagentkit/langchain-getyoutubetranscript#readme"
+Repository = "https://github.com/tubeagentkit/langchain-getyoutubetranscript"
+"API reference" = "https://getyoutubetranscript.com/docs"
+"Get an API key" = "https://getyoutubetranscript.com/dashboard"
+
+[tool.hatch.build.targets.wheel]
+packages = ["langchain_getyoutubetranscript"]
+
+[tool.ruff]
+line-length = 120
+
+[tool.pytest.ini_options]
+testpaths = ["tests/unit_tests"]

langchain_getyoutubetranscript-0.1.0/tests/integration_tests/test_live.py

@@ -0,0 +1,40 @@
+"""Live tests against the real API. Skipped unless GETYOUTUBETRANSCRIPT_API_KEY is set; each run spends credits."""
+
+from __future__ import annotations
+
+import json
+import os
+
+import pytest
+
+from langchain_getyoutubetranscript import (
+    GetYouTubeTranscriptLoader,
+    GetYouTubeTranscriptSearchTool,
+    GetYouTubeTranscriptTool,
+)
+
+pytestmark = pytest.mark.skipif(not os.environ.get("GETYOUTUBETRANSCRIPT_API_KEY"), reason="no API key")
+VIDEO = "https://youtu.be/5e37ZT3SQbk"
+
+
+def test_tool_timestamps():
+    out = GetYouTubeTranscriptTool().invoke({"video": VIDEO, "timestamps": True})
+    lines = [line for line in out.splitlines() if line.startswith("[")]
+    assert out.startswith("Title: ")
+    assert len(lines) > 400
+
+
+def test_tool_bad_video_returns_message():
+    out = GetYouTubeTranscriptTool().invoke({"video": "notavalidvideo"})
+    assert "YouTube video" in out
+
+
+def test_search_tool():
+    data = json.loads(GetYouTubeTranscriptSearchTool().invoke({"query": "linear algebra lecture"}))
+    assert data["video_results"]
+
+
+def test_loader():
+    doc = GetYouTubeTranscriptLoader(VIDEO).load()[0]
+    assert doc.metadata["video_id"] == "5e37ZT3SQbk"
+    assert len(doc.page_content) > 10_000

langchain_getyoutubetranscript-0.1.0/tests/unit_tests/test_document_loaders.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+import pytest
+
+from langchain_getyoutubetranscript import GetYouTubeTranscriptLoader
+
+RESULT = {
+    "video_id": "jNQXAC9IVRw",
+    "language_code": "en",
+    "title": "Me at the zoo",
+    "author_name": "jawed",
+    "transcript": "All right, so here we are",
+    "word_count": 6,
+    "segments": [{"start": 61.0, "duration": 2.0, "text": "All right, so here we are"}],
+}
+
+
+def _loader(**kwargs) -> tuple[GetYouTubeTranscriptLoader, MagicMock]:
+    loader = GetYouTubeTranscriptLoader(api_key="test-key", **kwargs)
+    client = MagicMock()
+    client.get_transcript.return_value = RESULT
+    loader._client = client
+    return loader, client
+
+
+def test_one_document_per_video_with_metadata():
+    loader, client = _loader(videos=["a", "b"], language="en")
+    docs = loader.load()
+    assert len(docs) == 2
+    assert client.get_transcript.call_args.kwargs == {"language": "en", "timestamps": False}
+    assert docs[0].page_content == "All right, so here we are"
+    assert docs[0].metadata == {
+        "source": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
+        "video_id": "jNQXAC9IVRw",
+        "title": "Me at the zoo",
+        "author_name": "jawed",
+        "language_code": "en",
+        "word_count": 6,
+    }
+
+
+def test_timestamps_give_timed_text_and_segments():
+    loader, _ = _loader(videos="a", timestamps=True)
+    doc = loader.load()[0]
+    assert doc.page_content == "[1:01] All right, so here we are"
+    assert doc.metadata["segments"] == RESULT["segments"]
+
+
+def test_missing_key(monkeypatch):
+    monkeypatch.delenv("GETYOUTUBETRANSCRIPT_API_KEY", raising=False)
+    with pytest.raises(ValueError, match="API key is required"):
+        GetYouTubeTranscriptLoader("a")

langchain_getyoutubetranscript-0.1.0/tests/unit_tests/test_tools.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import json
+from unittest.mock import MagicMock
+
+import pytest
+from getyoutubetranscript import GetYouTubeTranscriptError
+from langchain_tests.unit_tests import ToolsUnitTests
+
+from langchain_getyoutubetranscript import GetYouTubeTranscriptSearchTool, GetYouTubeTranscriptTool
+
+RESULT = {
+    "video_id": "jNQXAC9IVRw",
+    "language_code": "en",
+    "title": "Me at the zoo",
+    "author_name": "jawed",
+    "transcript": "All right, so here we are",
+    "word_count": 6,
+    "segments": [{"start": 1.2, "duration": 2.16, "text": "All right, so here we are"}],
+}
+
+
+class TestTranscriptToolStandard(ToolsUnitTests):
+    @property
+    def tool_constructor(self) -> type[GetYouTubeTranscriptTool]:
+        return GetYouTubeTranscriptTool
+
+    @property
+    def tool_constructor_params(self) -> dict:
+        return {"api_key": "test-key"}
+
+    @property
+    def tool_invoke_params_example(self) -> dict:
+        return {"video": "jNQXAC9IVRw", "language": "en", "timestamps": True}
+
+    @property
+    def init_from_env_params(self) -> tuple[dict, dict, dict]:
+        return ({"GETYOUTUBETRANSCRIPT_API_KEY": "env-key"}, {}, {"api_key": "env-key"})
+
+
+class TestSearchToolStandard(ToolsUnitTests):
+    @property
+    def tool_constructor(self) -> type[GetYouTubeTranscriptSearchTool]:
+        return GetYouTubeTranscriptSearchTool
+
+    @property
+    def tool_constructor_params(self) -> dict:
+        return {"api_key": "test-key"}
+
+    @property
+    def tool_invoke_params_example(self) -> dict:
+        return {"query": "linear algebra", "type": "video"}
+
+
+def _tool_with(cls, client: MagicMock):
+    tool = cls(api_key="test-key")
+    tool._client = client
+    return tool
+
+
+def test_transcript_plain_text():
+    client = MagicMock()
+    client.get_transcript.return_value = {k: v for k, v in RESULT.items() if k != "segments"}
+    out = _tool_with(GetYouTubeTranscriptTool, client).invoke({"video": "https://youtu.be/jNQXAC9IVRw"})
+    client.get_transcript.assert_called_once_with("https://youtu.be/jNQXAC9IVRw", language=None, timestamps=False)
+    assert out == "Title: Me at the zoo\nChannel: jawed\nLanguage: en\n\nAll right, so here we are"
+
+
+def test_transcript_timestamps():
+    client = MagicMock()
+    client.get_transcript.return_value = RESULT
+    out = _tool_with(GetYouTubeTranscriptTool, client).invoke({"video": "jNQXAC9IVRw", "timestamps": True})
+    assert out.endswith("\n\n[0:01] All right, so here we are")
+
+
+def test_api_error_is_returned_to_the_agent_not_raised():
+    client = MagicMock()
+    client.get_transcript.side_effect = GetYouTubeTranscriptError(
+        "INVALID_URL", "Not a recognizable YouTube video URL or id.", 400
+    )
+    out = _tool_with(GetYouTubeTranscriptTool, client).invoke({"video": "nope"})
+    assert out == "Not a recognizable YouTube video URL or id."
+
+
+def test_search_returns_json():
+    client = MagicMock()
+    client.search.return_value = {"video_results": [{"title": "x"}], "continuation_token": "t"}
+    out = _tool_with(GetYouTubeTranscriptSearchTool, client).invoke(
+        {"query": "q", "type": "channel", "page_token": "p"}
+    )
+    client.search.assert_called_once_with("q", type="channel", page_token="p")
+    assert json.loads(out)["continuation_token"] == "t"
+
+
+def test_missing_key_explains_how_to_get_one(monkeypatch):
+    monkeypatch.delenv("GETYOUTUBETRANSCRIPT_API_KEY", raising=False)
+    with pytest.raises(ValueError, match="GETYOUTUBETRANSCRIPT_API_KEY"):
+        _ = GetYouTubeTranscriptTool().client