feat: modernize langchain integration native components

langchain_apify/__init__.py

@@ -1,19 +1,71 @@
+from __future__ import annotations
+
 from importlib import metadata
+from typing import TYPE_CHECKING
 
-from langchain_apify.document_loaders import ApifyDatasetLoader
-from langchain_apify.tools import ApifyActorsTool
+from langchain_apify._actor_tools import ApifyGoogleSearchTool, ApifyWebCrawlerTool
+from langchain_apify.document_loaders import ApifyCrawlLoader, ApifyDatasetLoader
+from langchain_apify.retrievers import ApifySearchRetriever
+from langchain_apify.tools import (
+    ApifyActorsTool,
+    ApifyGetDatasetItemsTool,
+    ApifyRunActorAndGetDatasetTool,
+    ApifyRunActorTool,
+    ApifyRunTaskAndGetDatasetTool,
+    ApifyRunTaskTool,
+    ApifyScrapeUrlTool,
+)
 from langchain_apify.wrappers import ApifyWrapper
 
+if TYPE_CHECKING:
+    from langchain_core.tools import BaseTool
+
 try:
     __version__ = metadata.version(__package__)
 except metadata.PackageNotFoundError:
-    # Case where package metadata is not available.
     __version__ = ''
 del metadata  # optional, avoids polluting the results of dir(__package__)
 
+# Convenience tool-class lists for selective agent binding.
+# Binding all tools at once overwhelms the LLM context window;
+# pick the group(s) relevant to your use case.
+
+APIFY_CORE_TOOLS: list[type[BaseTool]] = [
+    ApifyRunActorTool,
+    ApifyGetDatasetItemsTool,
+    ApifyRunActorAndGetDatasetTool,
+    ApifyScrapeUrlTool,
+    ApifyRunTaskTool,
+    ApifyRunTaskAndGetDatasetTool,
+]
+
+APIFY_SEARCH_TOOLS: list[type[BaseTool]] = [
+    ApifyGoogleSearchTool,
+    ApifyWebCrawlerTool,
+]
+
 __all__ = [
+    # Existing components (backward-compatible)
     'ApifyActorsTool',
     'ApifyDatasetLoader',
     'ApifyWrapper',
+    # Core generic tools
+    'ApifyGetDatasetItemsTool',
+    'ApifyRunActorAndGetDatasetTool',
+    'ApifyRunActorTool',
+    'ApifyRunTaskAndGetDatasetTool',
+    'ApifyRunTaskTool',
+    'ApifyScrapeUrlTool',
+    # Actor-specific tools
+    'ApifyGoogleSearchTool',
+    'ApifyWebCrawlerTool',
+    # Retriever
+    'ApifySearchRetriever',
+    # Loaders
+    'ApifyCrawlLoader',
+    # Tool group lists
+    'APIFY_SEARCH_TOOLS',
+    'APIFY_CORE_TOOLS',
+    # Meta
     '__version__',
 ]

langchain_apify/_actor_tools.py

@@ -0,0 +1,158 @@
+"""Actor-specific tool subclasses.
+
+Tools in this module wrap a single Apify Actor behind a simplified,
+LLM-friendly interface. They inherit from
+:class:`~langchain_apify.tools._ApifyGenericTool`.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+from langchain_core.tools import ToolException
+from pydantic import BaseModel  # noqa: TCH002
+
+from langchain_apify.tools import (
+    ApifyGoogleSearchInput,
+    ApifyWebCrawlerInput,
+    CrawlerType,
+    _ApifyGenericTool,
+)
+
+if TYPE_CHECKING:
+    from langchain_core.callbacks import CallbackManagerForToolRun
+
+# ---------------------------------------------------------------------------
+# Search & Crawling tools
+# ---------------------------------------------------------------------------
+
+
+class ApifyGoogleSearchTool(_ApifyGenericTool):  # type: ignore[override]
+    """Search Google and return structured results via Apify.
+
+    Wraps the ``apify/google-search-scraper`` Actor behind a simplified,
+    LLM-friendly interface.  Returns a JSON string containing an array of
+    result objects, each with ``title``, ``url``, and ``description`` keys.
+
+    Args:
+        apify_api_token: Apify API token. Falls back to the ``APIFY_API_TOKEN``
+            environment variable when *None*.
+
+    Returns:
+        JSON string — an array of ``{"title", "url", "description"}`` objects.
+
+    Example:
+        .. code-block:: python
+
+            import os
+            os.environ["APIFY_API_TOKEN"] = "your-apify-api-token"
+
+            from langchain_apify import ApifyGoogleSearchTool
+
+            tool = ApifyGoogleSearchTool()
+            results = tool.invoke({"query": "LangChain framework"})
+    """
+
+    name: str = 'apify_google_search'
+    description: str = (
+        'Search Google using Apify and return structured results as a JSON array.'
+        ' Each result has keys: title, url, description.'
+        ' Required: query (str) — the search query.'
+        ' Optional: max_results (int, default 10),'
+        ' country_code (str|null), language_code (str|null),'
+        ' timeout_secs (int, default 300).'
+    )
+    args_schema: type[BaseModel] = ApifyGoogleSearchInput
+
+    def _run(
+        self,
+        query: str,
+        max_results: int = 10,
+        country_code: str | None = None,
+        language_code: str | None = None,
+        timeout_secs: int = 300,
+        _run_manager: CallbackManagerForToolRun | None = None,
+    ) -> str:
+        try:
+            results = self._client.google_search(
+                query,
+                max_results=self._clamp_items(max_results),
+                country_code=country_code,
+                language_code=language_code,
+                timeout_secs=self._clamp_timeout(timeout_secs),
+            )
+        except RuntimeError as exc:
+            raise ToolException(str(exc)) from exc
+        return json.dumps(results)
+
+
+class ApifyWebCrawlerTool(_ApifyGenericTool):  # type: ignore[override]
+    """Crawl a website and return page content as JSON via Apify.
+
+    Wraps the ``apify/website-content-crawler`` Actor.  Returns a JSON string
+    containing an array of page objects, each with ``url``, ``title``, and
+    ``content`` (markdown) keys.
+
+    Args:
+        apify_api_token: Apify API token. Falls back to the ``APIFY_API_TOKEN``
+            environment variable when *None*.
+
+    Returns:
+        JSON string — an array of ``{"url", "title", "content"}`` objects.
+
+    Example:
+        .. code-block:: python
+
+            import os
+            os.environ["APIFY_API_TOKEN"] = "your-apify-api-token"
+
+            from langchain_apify import ApifyWebCrawlerTool
+
+            tool = ApifyWebCrawlerTool()
+            pages = tool.invoke({
+                "url": "https://docs.apify.com",
+                "max_crawl_pages": 5,
+            })
+    """
+
+    name: str = 'apify_web_crawler'
+    description: str = (
+        'Crawl a website using Apify and return page content as a JSON array.'
+        ' Each page object has keys: url, title, content (markdown).'
+        ' Required: url (str) — seed URL to crawl.'
+        ' Optional: max_crawl_pages (int, default 10),'
+        ' max_crawl_depth (int, default 1),'
+        ' crawler_type (str, default "cheerio"),'
+        ' timeout_secs (int, default 300).'
+    )
+    args_schema: type[BaseModel] = ApifyWebCrawlerInput
+
+    def _run(
+        self,
+        url: str,
+        max_crawl_pages: int = 10,
+        max_crawl_depth: int = 1,
+        crawler_type: CrawlerType = 'cheerio',
+        timeout_secs: int = 300,
+        _run_manager: CallbackManagerForToolRun | None = None,
+    ) -> str:
+        try:
+            items = self._client.crawl_website(
+                url,
+                max_crawl_pages=self._clamp_items(max_crawl_pages),
+                max_crawl_depth=self._clamp_depth(max_crawl_depth),
+                crawler_type=crawler_type,
+                timeout_secs=self._clamp_timeout(timeout_secs),
+            )
+        except RuntimeError as exc:
+            raise ToolException(str(exc)) from exc
+        pages = [
+            {
+                'url': item.get('url', ''),
+                'title': item.get('metadata', {}).get('title', ''),
+                'content': item.get('markdown') or item.get('text', ''),
+            }
+            for item in items
+        ]
+        return json.dumps(pages)