crewai-transcriptapi 0.1.0__tar.gz

crewai_transcriptapi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TranscriptAPI (ZeroPointRepo)
+
+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.

crewai_transcriptapi-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: crewai-transcriptapi
+Version: 0.1.0
+Summary: CrewAI tools for TranscriptAPI: fetch YouTube transcripts and search YouTube videos and channels from CrewAI agents.
+Project-URL: Homepage, https://transcriptapi.com
+Project-URL: Documentation, https://transcriptapi.com/docs
+Project-URL: Repository, https://github.com/ZeroPointRepo/crewai-transcriptapi
+Author-email: Zero Point Studio <hello@transcriptapi.com>
+License: MIT License
+        
+        Copyright (c) 2026 TranscriptAPI (ZeroPointRepo)
+        
+        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.
+License-File: LICENSE
+Keywords: ai-agent,crewai,crewai-tools,llm,transcript,transcriptapi,youtube,youtube-api,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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: crewai>=0.80.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: requests>=2.31.0
+Description-Content-Type: text/markdown
+
+# crewai-transcriptapi
+
+**TranscriptAPI: hosted YouTube transcript + video-discovery API for AI agents.** CrewAI tools edition. Also available as an [n8n community node](https://github.com/ZeroPointRepo/n8n-nodes-transcriptapi), an [MCP server](https://github.com/ZeroPointRepo/youtube-mcp) and [agent skills](https://github.com/ZeroPointRepo/youtube-skills).
+
+This package gives [CrewAI](https://www.crewai.com/) agents two tools over [TranscriptAPI](https://transcriptapi.com):
+
+- **TranscriptAPITool**: fetch the transcript of any YouTube video (full URL, youtu.be, Shorts, or bare ID) as plain text or timestamped JSON, with metadata. The hero tool: 1 credit per call.
+- **TranscriptAPISearchTool**: search YouTube for videos or channels to discover content before fetching transcripts. 1 credit per page.
+
+## Installation
+
+```bash
+pip install crewai-transcriptapi
+```
+
+## Credentials
+
+You need a TranscriptAPI key (starts with `sk_`):
+
+1. Create an account at [transcriptapi.com](https://transcriptapi.com): **100 free credits, no card (one-time)**; paid plans from **$5/mo (1,000 credits)**.
+2. Create an API key on the dashboard.
+3. Export it:
+
+```bash
+export TRANSCRIPTAPI_API_KEY="sk_..."
+```
+
+## Usage
+
+```python
+from crewai import Agent
+from crewai_transcriptapi import TranscriptAPITool, TranscriptAPISearchTool
+
+researcher = Agent(
+    role="Video researcher",
+    goal="Find and summarize YouTube content on a topic",
+    backstory="Researches spoken video content via transcripts.",
+    tools=[TranscriptAPISearchTool(), TranscriptAPITool()],
+)
+```
+
+The agent can then search for videos on a topic and fetch each transcript for summarizing, quoting, translating or analysis.
+
+## Tool reference
+
+### TranscriptAPITool
+
+| Argument | Type | Default | Description |
+|---|---|---|---|
+| `video_url` | str | required | Full YouTube URL (watch, youtu.be, embed, Shorts) or bare 11-character video ID |
+| `output_format` | str | `"text"` | `"text"` for plain transcript, `"json"` for timestamped segments |
+| `language` | str | none | Optional preferred transcript language code, for example `"es"` |
+
+### TranscriptAPISearchTool
+
+| Argument | Type | Default | Description |
+|---|---|---|---|
+| `query` | str | required | Search query, 1 to 200 characters |
+| `search_type` | str | `"video"` | `"video"` or `"channel"` |
+
+## Response envelope
+
+Both tools return a stable JSON string and never raise:
+
+```json
+{"success": true, "data": {"transcript": "...", "metadata": {"title": "..."}}}
+```
+
+```json
+{"success": false, "error": {"code": "out_of_credits", "message": "The account is out of credits. See https://transcriptapi.com/billing."}}
+```
+
+Error codes: `missing_api_key`, `invalid_api_key`, `out_of_credits`, `not_found`, `rate_limited`, `network`, `bad_response`, `http_<status>`. Failed calls are never charged.
+
+## Resources
+
+- [TranscriptAPI documentation](https://transcriptapi.com/docs)
+- [Pricing](https://transcriptapi.com)
+- Family: [n8n node](https://github.com/ZeroPointRepo/n8n-nodes-transcriptapi) · [MCP server](https://github.com/ZeroPointRepo/youtube-mcp) · [agent skills](https://github.com/ZeroPointRepo/youtube-skills)
+
+## Disclosure
+
+TranscriptAPI is an independent product and is not affiliated with or endorsed by YouTube or Google. Use of these tools is subject to the [TranscriptAPI terms](https://transcriptapi.com/terms).
+
+## License
+
+[MIT](LICENSE)

crewai_transcriptapi-0.1.0/README.md

@@ -0,0 +1,87 @@
+# crewai-transcriptapi
+
+**TranscriptAPI: hosted YouTube transcript + video-discovery API for AI agents.** CrewAI tools edition. Also available as an [n8n community node](https://github.com/ZeroPointRepo/n8n-nodes-transcriptapi), an [MCP server](https://github.com/ZeroPointRepo/youtube-mcp) and [agent skills](https://github.com/ZeroPointRepo/youtube-skills).
+
+This package gives [CrewAI](https://www.crewai.com/) agents two tools over [TranscriptAPI](https://transcriptapi.com):
+
+- **TranscriptAPITool**: fetch the transcript of any YouTube video (full URL, youtu.be, Shorts, or bare ID) as plain text or timestamped JSON, with metadata. The hero tool: 1 credit per call.
+- **TranscriptAPISearchTool**: search YouTube for videos or channels to discover content before fetching transcripts. 1 credit per page.
+
+## Installation
+
+```bash
+pip install crewai-transcriptapi
+```
+
+## Credentials
+
+You need a TranscriptAPI key (starts with `sk_`):
+
+1. Create an account at [transcriptapi.com](https://transcriptapi.com): **100 free credits, no card (one-time)**; paid plans from **$5/mo (1,000 credits)**.
+2. Create an API key on the dashboard.
+3. Export it:
+
+```bash
+export TRANSCRIPTAPI_API_KEY="sk_..."
+```
+
+## Usage
+
+```python
+from crewai import Agent
+from crewai_transcriptapi import TranscriptAPITool, TranscriptAPISearchTool
+
+researcher = Agent(
+    role="Video researcher",
+    goal="Find and summarize YouTube content on a topic",
+    backstory="Researches spoken video content via transcripts.",
+    tools=[TranscriptAPISearchTool(), TranscriptAPITool()],
+)
+```
+
+The agent can then search for videos on a topic and fetch each transcript for summarizing, quoting, translating or analysis.
+
+## Tool reference
+
+### TranscriptAPITool
+
+| Argument | Type | Default | Description |
+|---|---|---|---|
+| `video_url` | str | required | Full YouTube URL (watch, youtu.be, embed, Shorts) or bare 11-character video ID |
+| `output_format` | str | `"text"` | `"text"` for plain transcript, `"json"` for timestamped segments |
+| `language` | str | none | Optional preferred transcript language code, for example `"es"` |
+
+### TranscriptAPISearchTool
+
+| Argument | Type | Default | Description |
+|---|---|---|---|
+| `query` | str | required | Search query, 1 to 200 characters |
+| `search_type` | str | `"video"` | `"video"` or `"channel"` |
+
+## Response envelope
+
+Both tools return a stable JSON string and never raise:
+
+```json
+{"success": true, "data": {"transcript": "...", "metadata": {"title": "..."}}}
+```
+
+```json
+{"success": false, "error": {"code": "out_of_credits", "message": "The account is out of credits. See https://transcriptapi.com/billing."}}
+```
+
+Error codes: `missing_api_key`, `invalid_api_key`, `out_of_credits`, `not_found`, `rate_limited`, `network`, `bad_response`, `http_<status>`. Failed calls are never charged.
+
+## Resources
+
+- [TranscriptAPI documentation](https://transcriptapi.com/docs)
+- [Pricing](https://transcriptapi.com)
+- Family: [n8n node](https://github.com/ZeroPointRepo/n8n-nodes-transcriptapi) · [MCP server](https://github.com/ZeroPointRepo/youtube-mcp) · [agent skills](https://github.com/ZeroPointRepo/youtube-skills)
+
+## Disclosure
+
+TranscriptAPI is an independent product and is not affiliated with or endorsed by YouTube or Google. Use of these tools is subject to the [TranscriptAPI terms](https://transcriptapi.com/terms).
+
+## License
+
+[MIT](LICENSE)

crewai_transcriptapi-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "crewai-transcriptapi"
+version = "0.1.0"
+description = "CrewAI tools for TranscriptAPI: fetch YouTube transcripts and search YouTube videos and channels from CrewAI agents."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors = [{ name = "Zero Point Studio", email = "hello@transcriptapi.com" }]
+keywords = [
+  "crewai",
+  "crewai-tools",
+  "transcriptapi",
+  "youtube",
+  "youtube-transcript",
+  "transcript",
+  "youtube-api",
+  "ai-agent",
+  "llm",
+]
+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",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["crewai>=0.80.0", "requests>=2.31.0", "pydantic>=2.0.0"]
+
+[project.urls]
+Homepage = "https://transcriptapi.com"
+Documentation = "https://transcriptapi.com/docs"
+Repository = "https://github.com/ZeroPointRepo/crewai-transcriptapi"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/crewai_transcriptapi"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "pyproject.toml"]

crewai_transcriptapi-0.1.0/src/crewai_transcriptapi/__init__.py

@@ -0,0 +1,21 @@
+"""crewai-transcriptapi: CrewAI tools for TranscriptAPI (transcriptapi.com)."""
+
+from .transcriptapi_tool import (
+    TranscriptAPISearchToolSchema,
+    TranscriptAPIToolSchema,
+)
+
+try:
+    from .transcriptapi_tool import TranscriptAPISearchTool, TranscriptAPITool
+except ImportError:  # pragma: no cover - crewai not installed
+    pass
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "TranscriptAPITool",
+    "TranscriptAPISearchTool",
+    "TranscriptAPIToolSchema",
+    "TranscriptAPISearchToolSchema",
+    "__version__",
+]

crewai_transcriptapi-0.1.0/src/crewai_transcriptapi/transcriptapi_tool.py

@@ -0,0 +1,182 @@
+"""CrewAI tools for TranscriptAPI (transcriptapi.com).
+
+Two tools following the crewai-tools BaseTool conventions:
+
+- TranscriptAPITool: fetch the transcript of a YouTube video (the hero use case)
+- TranscriptAPISearchTool: search YouTube for videos or channels
+
+Both return a stable JSON string envelope and never leak exceptions:
+  {"success": true, "data": {...}}
+  {"success": false, "error": {"code": "...", "message": "..."}}
+
+Auth: TRANSCRIPTAPI_API_KEY environment variable (Bearer key, "sk_..." format).
+"""
+
+import json
+import os
+from typing import Any, Optional, Type
+
+from pydantic import BaseModel, ConfigDict, Field
+
+try:  # crewai is the runtime host; keep the import lazy-friendly for tests
+    from crewai.tools import BaseTool, EnvVar
+except ImportError:  # pragma: no cover - exercised only without crewai installed
+    BaseTool = None  # type: ignore[assignment,misc]
+    EnvVar = None  # type: ignore[assignment,misc]
+
+BASE_URL = "https://transcriptapi.com/api/v2"
+USER_AGENT = "crewai-transcriptapi/0.1.0 (+https://github.com/ZeroPointRepo/crewai-transcriptapi)"
+TIMEOUT_SECONDS = 60
+
+_ENV_KEY = "TRANSCRIPTAPI_API_KEY"
+
+_ENV_VARS = (
+    [
+        EnvVar(
+            name=_ENV_KEY,
+            description=(
+                "TranscriptAPI key (starts with sk_). Create one at "
+                "https://transcriptapi.com: 100 free credits, no card (one-time)."
+            ),
+            required=True,
+        )
+    ]
+    if EnvVar is not None
+    else []
+)
+
+
+def _envelope_error(code: str, message: str) -> str:
+    return json.dumps({"success": False, "error": {"code": code, "message": message}})
+
+
+def _request(path: str, params: dict) -> str:
+    """GET a TranscriptAPI endpoint and return the JSON string envelope."""
+    key = os.environ.get(_ENV_KEY, "").strip()
+    if not key:
+        return _envelope_error(
+            "missing_api_key",
+            f"{_ENV_KEY} is not set. Get a free key at https://transcriptapi.com "
+            "(100 free credits, no card, one-time).",
+        )
+    import requests  # lazy import so tests can stub it
+
+    try:
+        response = requests.get(
+            BASE_URL + path,
+            params={k: v for k, v in params.items() if v is not None},
+            headers={
+                "Authorization": f"Bearer {key}",
+                "User-Agent": USER_AGENT,
+                "Accept": "application/json",
+            },
+            timeout=TIMEOUT_SECONDS,
+        )
+    except requests.exceptions.RequestException as exc:
+        return _envelope_error("network", str(exc))
+    if response.status_code != 200:
+        code = {
+            401: "invalid_api_key",
+            402: "out_of_credits",
+            404: "not_found",
+            429: "rate_limited",
+        }.get(response.status_code, f"http_{response.status_code}")
+        message = {
+            401: "The API key was rejected. Check TRANSCRIPTAPI_API_KEY.",
+            402: "The account is out of credits. See https://transcriptapi.com/billing.",
+            404: "Not found: the video may not exist or has no captions.",
+            429: "Rate limited. Wait and retry, respecting the Retry-After header.",
+        }.get(response.status_code, response.text[:300])
+        return _envelope_error(code, message)
+    try:
+        data = response.json()
+    except ValueError:
+        return _envelope_error("bad_response", "The API returned a non-JSON response.")
+    return json.dumps({"success": True, "data": data})
+
+
+class TranscriptAPIToolSchema(BaseModel):
+    """Input for TranscriptAPITool."""
+
+    video_url: str = Field(
+        ...,
+        min_length=6,
+        description=(
+            "Full YouTube URL (watch, youtu.be, embed, or Shorts) or the bare "
+            "11-character video ID"
+        ),
+    )
+    output_format: str = Field(
+        default="text",
+        pattern="^(text|json)$",
+        description='Transcript format: "text" (plain transcript) or "json" (timestamped segments)',
+    )
+    language: Optional[str] = Field(
+        default=None,
+        description="Optional preferred transcript language code, for example 'es'",
+    )
+
+
+class TranscriptAPISearchToolSchema(BaseModel):
+    """Input for TranscriptAPISearchTool."""
+
+    query: str = Field(..., min_length=1, max_length=200, description="Search query")
+    search_type: str = Field(
+        default="video",
+        pattern="^(video|channel)$",
+        description='What to search for: "video" or "channel"',
+    )
+
+
+if BaseTool is not None:
+
+    class TranscriptAPITool(BaseTool):
+        """Fetch the transcript of a YouTube video via TranscriptAPI."""
+
+        model_config = ConfigDict(arbitrary_types_allowed=True)
+        name: str = "TranscriptAPI YouTube Transcript"
+        description: str = (
+            "Fetches the transcript of a YouTube video, with metadata, via the "
+            "TranscriptAPI service. Accepts a full YouTube URL (watch, youtu.be, "
+            "embed, Shorts) or a bare 11-character video ID. Use when the task "
+            "needs the spoken content of a specific video: summarizing, quoting, "
+            "translating or analyzing it. Costs 1 credit per successful call."
+        )
+        args_schema: Type[BaseModel] = TranscriptAPIToolSchema
+        package_dependencies: list = Field(default_factory=lambda: ["requests"])
+        env_vars: list = Field(default_factory=lambda: list(_ENV_VARS))
+
+        def _run(self, **kwargs: Any) -> str:
+            args = TranscriptAPIToolSchema(**kwargs)
+            return _request(
+                "/youtube/transcript",
+                {
+                    "video_url": args.video_url,
+                    "format": args.output_format,
+                    "send_metadata": "true",
+                    "language": args.language,
+                },
+            )
+
+    class TranscriptAPISearchTool(BaseTool):
+        """Search YouTube for videos or channels via TranscriptAPI."""
+
+        model_config = ConfigDict(arbitrary_types_allowed=True)
+        name: str = "TranscriptAPI YouTube Search"
+        description: str = (
+            "Searches YouTube for videos or channels via the TranscriptAPI "
+            "service and returns titles, IDs, thumbnails, view counts and "
+            "publish dates. Use when the task needs to discover videos or "
+            "channels about a topic before fetching transcripts. Costs 1 credit "
+            "per page of results."
+        )
+        args_schema: Type[BaseModel] = TranscriptAPISearchToolSchema
+        package_dependencies: list = Field(default_factory=lambda: ["requests"])
+        env_vars: list = Field(default_factory=lambda: list(_ENV_VARS))
+
+        def _run(self, **kwargs: Any) -> str:
+            args = TranscriptAPISearchToolSchema(**kwargs)
+            return _request(
+                "/youtube/search",
+                {"q": args.query, "type": args.search_type},
+            )

crewai_transcriptapi-0.1.0/tests/test_transcriptapi_tool.py

@@ -0,0 +1,175 @@
+"""Tests for crewai-transcriptapi. No network, no crewai install required.
+
+crewai.tools is stubbed with faithful pydantic-based stand-ins BEFORE the tool
+module imports (the DB2 test pattern: stub optional externals so import-time
+validation still runs through real pydantic).
+"""
+
+import json
+import os
+import sys
+import types
+import unittest
+from unittest import mock
+
+from pydantic import BaseModel
+
+# ── stub crewai.tools before importing the module under test ─────────────────
+crewai_mod = types.ModuleType("crewai")
+tools_mod = types.ModuleType("crewai.tools")
+
+
+class BaseTool(BaseModel):
+    """Faithful minimal stand-in: pydantic model with a run() entrypoint."""
+
+    name: str = ""
+    description: str = ""
+
+    def run(self, **kwargs):
+        return self._run(**kwargs)
+
+
+class EnvVar(BaseModel):
+    name: str
+    description: str = ""
+    required: bool = False
+
+
+tools_mod.BaseTool = BaseTool
+tools_mod.EnvVar = EnvVar
+crewai_mod.tools = tools_mod
+sys.modules.setdefault("crewai", crewai_mod)
+sys.modules["crewai.tools"] = tools_mod
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from crewai_transcriptapi.transcriptapi_tool import (  # noqa: E402
+    TranscriptAPISearchTool,
+    TranscriptAPISearchToolSchema,
+    TranscriptAPITool,
+    TranscriptAPIToolSchema,
+)
+
+
+def _fake_response(status=200, payload=None, text=""):
+    resp = mock.Mock()
+    resp.status_code = status
+    resp.text = text
+    if payload is None:
+        resp.json.side_effect = ValueError("no json")
+    else:
+        resp.json.return_value = payload
+    return resp
+
+
+class SchemaTests(unittest.TestCase):
+    def test_transcript_schema_requires_video_url(self):
+        with self.assertRaises(Exception):
+            TranscriptAPIToolSchema()
+
+    def test_transcript_schema_rejects_bad_format(self):
+        with self.assertRaises(Exception):
+            TranscriptAPIToolSchema(video_url="dQw4w9WgXcQ", output_format="xml")
+
+    def test_transcript_schema_defaults(self):
+        s = TranscriptAPIToolSchema(video_url="dQw4w9WgXcQ")
+        self.assertEqual(s.output_format, "text")
+        self.assertIsNone(s.language)
+
+    def test_search_schema_bounds(self):
+        with self.assertRaises(Exception):
+            TranscriptAPISearchToolSchema(query="")
+        with self.assertRaises(Exception):
+            TranscriptAPISearchToolSchema(query="x", search_type="playlist")
+
+
+class EnvTests(unittest.TestCase):
+    def test_missing_key_returns_envelope_not_exception(self):
+        with mock.patch.dict(os.environ, {}, clear=True):
+            out = json.loads(TranscriptAPITool().run(video_url="dQw4w9WgXcQ"))
+        self.assertFalse(out["success"])
+        self.assertEqual(out["error"]["code"], "missing_api_key")
+
+    def test_env_vars_declared(self):
+        tool = TranscriptAPITool()
+        self.assertEqual(tool.env_vars[0].name, "TRANSCRIPTAPI_API_KEY")
+        self.assertTrue(tool.env_vars[0].required)
+
+
+class RequestTests(unittest.TestCase):
+    def _run_with(self, resp, **kwargs):
+        with mock.patch.dict(os.environ, {"TRANSCRIPTAPI_API_KEY": "sk_test"}, clear=True):
+            with mock.patch("requests.get", return_value=resp) as getter:
+                out = json.loads(TranscriptAPITool().run(**kwargs))
+        return out, getter
+
+    def test_request_construction(self):
+        resp = _fake_response(payload={"transcript": "hello", "video_id": "dQw4w9WgXcQ"})
+        out, getter = self._run_with(
+            resp, video_url="dQw4w9WgXcQ", output_format="json", language="es"
+        )
+        self.assertTrue(out["success"])
+        url = getter.call_args.args[0]
+        kwargs = getter.call_args.kwargs
+        self.assertEqual(url, "https://transcriptapi.com/api/v2/youtube/transcript")
+        self.assertEqual(kwargs["params"]["video_url"], "dQw4w9WgXcQ")
+        self.assertEqual(kwargs["params"]["format"], "json")
+        self.assertEqual(kwargs["params"]["language"], "es")
+        self.assertEqual(kwargs["headers"]["Authorization"], "Bearer sk_test")
+        self.assertIn("crewai-transcriptapi", kwargs["headers"]["User-Agent"])
+
+    def test_language_omitted_when_none(self):
+        resp = _fake_response(payload={"transcript": "hi"})
+        _, getter = self._run_with(resp, video_url="dQw4w9WgXcQ")
+        self.assertNotIn("language", getter.call_args.kwargs["params"])
+
+    def test_success_envelope(self):
+        resp = _fake_response(payload={"transcript": "hello world"})
+        out, _ = self._run_with(resp, video_url="dQw4w9WgXcQ")
+        self.assertTrue(out["success"])
+        self.assertEqual(out["data"]["transcript"], "hello world")
+
+    def test_402_maps_to_out_of_credits(self):
+        out, _ = self._run_with(_fake_response(status=402), video_url="dQw4w9WgXcQ")
+        self.assertFalse(out["success"])
+        self.assertEqual(out["error"]["code"], "out_of_credits")
+
+    def test_404_and_429_and_unknown(self):
+        for status, code in ((404, "not_found"), (429, "rate_limited"), (500, "http_500")):
+            out, _ = self._run_with(_fake_response(status=status), video_url="dQw4w9WgXcQ")
+            self.assertEqual(out["error"]["code"], code)
+
+    def test_network_error_envelope(self):
+        import requests
+
+        with mock.patch.dict(os.environ, {"TRANSCRIPTAPI_API_KEY": "sk_test"}, clear=True):
+            with mock.patch(
+                "requests.get",
+                side_effect=requests.exceptions.ConnectionError("boom"),
+            ):
+                out = json.loads(TranscriptAPITool().run(video_url="dQw4w9WgXcQ"))
+        self.assertEqual(out["error"]["code"], "network")
+
+    def test_non_json_body_envelope(self):
+        out, _ = self._run_with(_fake_response(payload=None), video_url="dQw4w9WgXcQ")
+        self.assertEqual(out["error"]["code"], "bad_response")
+
+
+class SearchToolTests(unittest.TestCase):
+    def test_search_request_and_envelope(self):
+        resp = _fake_response(payload={"results": [{"title": "a video"}]})
+        with mock.patch.dict(os.environ, {"TRANSCRIPTAPI_API_KEY": "sk_test"}, clear=True):
+            with mock.patch("requests.get", return_value=resp) as getter:
+                out = json.loads(
+                    TranscriptAPISearchTool().run(query="machine learning", search_type="channel")
+                )
+        self.assertTrue(out["success"])
+        self.assertEqual(
+            getter.call_args.args[0], "https://transcriptapi.com/api/v2/youtube/search"
+        )
+        self.assertEqual(getter.call_args.kwargs["params"]["q"], "machine learning")
+        self.assertEqual(getter.call_args.kwargs["params"]["type"], "channel")
+
+
+if __name__ == "__main__":
+    unittest.main()