crewai-transcriptapi 0.1.0__py3-none-any.whl

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,6 @@
+crewai_transcriptapi/__init__.py,sha256=O6IoZdJP4ej3chLOfzsUwtpdczMfvAD4Ndm-SFNaSD8,519
+crewai_transcriptapi/transcriptapi_tool.py,sha256=1tOVQnV8ZLaSQ-l-2x-IGKo9Kvk76CMUTBzBWMqspX0,6869
+crewai_transcriptapi-0.1.0.dist-info/METADATA,sha256=mSLCBU58Q6-GuFE5Er3-wY0OdvcF4fbdCQkRcEYLIKA,5780
+crewai_transcriptapi-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+crewai_transcriptapi-0.1.0.dist-info/licenses/LICENSE,sha256=hnkYxWklrAxDTGpOqg-2GDcHI7mE3SJ1RP_djjLpoFM,1086
+crewai_transcriptapi-0.1.0.dist-info/RECORD,,

crewai_transcriptapi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

crewai_transcriptapi-0.1.0.dist-info/licenses/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.