feat: add a transcription tool family (Facebook Ads, YouTube, media)

[steadyfetch]

What this adds

A fourth tool family: transcription. Three classes, exported together as APIFY_TRANSCRIPT_TOOLS.

Class	Actor	Input
ApifyFacebookAdsTranscriptTool	steadyfetch/facebook-ads-transcript-scraper	search_queries: list[str], country: str = "US", max_results
ApifyYouTubeTranscriptTool	steadyfetch/youtube-transcript-scraper	video_urls: list[str], max_results
ApifyMediaTranscriberTool	steadyfetch/media-transcriber	urls: list[str], max_results

Why

The existing families return what a page or a profile shows. None of them returns what is said inside a video or an audio file. An agent asked for the script of an ad it just found, the words in a YouTube video, or the text of a podcast episode has to drop to ApifyActorsTool and already know an Actor ID — so the capability is invisible to tool selection.

The three Actors are pay-per-event Actors we publish as steadyfetch, alongside the six third-party Actors already wrapped here (clockworks/tiktok-scraper, apimaestro/linkedin-profile-posts, harvestapi/linkedin-profile-search, apidojo/twitter-scraper-lite, compass/crawler-google-places, streamers/youtube-scraper). A run is charged to the caller's own Apify account at the price on each Actor's store page; no price appears anywhere in the code, since a released package cannot be corrected when one changes.

Shape

Modelled on tools/social.py — same input-schema style, same docstring and description shape, same _ApifyGenericTool envelope contract ({"run": {...}, "items": [...]}), Actor calls through ApifyToolsClient rather than the SDK, defaults in _constants.py, no new apify_api_token field, no hand-edited version or changelog.

Two small deliberate choices:

• max_results bounds the Actor's own work as well as the dataset read (maxAds/searchMaxAds and maxItems), so a clamped call cannot cost more than the caller asked for. It defaults to 10 rather than the social family's 20 because these Actors charge per delivered item.
• An empty list raises ValueError client-side (surfacing as ToolException). videoUrls and urls both carry a sample-run default on the Actor side, so an empty list would silently run a demo instead of failing.

Tests

tests/unit_tests/test_transcript_tools.py — 38 new tests: client-level run-input mapping per Actor, the empty-list guards, per-tool happy path, clamping, RuntimeError/ValueError → ToolException, empty datasets, datetime serialisation, envelope shape, and a check that no description carries a price. tests/unit_tests/test_merge_surface.py is extended with the new group (size, disjointness, globally unique tool names).

450 passed, 1 warning

ruff check, ruff format --check, mypy, codespell and scripts/check_imports.py all clean.

Note, unrelated to this PR

While checking what user-agent the package sends: _create_apify_client appends ; Origin/langchain by reaching for http_client.httpx_client / http_client.http_client, but apify-client 2.5.1 (inside the declared >=2.3.0,<3.0.0 range) exposes impit_client instead. Both getattr lookups return None, so the suffix is silently dropped and runs from this package are indistinguishable from any other ApifyClient caller. Happy to open a separate issue or PR for it.