autogen-scavio 0.1.0__tar.gz

autogen_scavio-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to PyPI
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

autogen_scavio-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+.env
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.claude/

autogen_scavio-0.1.0/LICENSE

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

autogen_scavio-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: autogen-scavio
+Version: 0.1.0
+Summary: AutoGen integration for Scavio Search API -- real-time Google, Amazon, Walmart, YouTube, Reddit, and TikTok search tools for AI agents
+Project-URL: Homepage, https://scavio.dev
+Project-URL: Repository, https://github.com/scavio-ai/autogen-scavio
+Project-URL: Documentation, https://scavio.dev/docs/autogen
+Author: Scavio
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ag2,agents,ai,amazon-search,autogen,reddit-search,scavio,search,tiktok-search,walmart-search,web-search,youtube-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: autogen-core>=0.4.0
+Requires-Dist: scavio>=0.1.1
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# autogen-scavio
+
+AutoGen integration for the [Scavio Search API](https://scavio.dev). Provides 20 search tools across Google, Amazon, Walmart, YouTube, Reddit, and TikTok for use with AutoGen AI agents.
+
+## Installation
+
+```bash
+pip install autogen-scavio
+```
+
+## Setup
+
+Get a free API key at [dashboard.scavio.dev](https://dashboard.scavio.dev) and set it as an environment variable:
+
+```bash
+export SCAVIO_API_KEY="sk_live_..."
+```
+
+## Quick Start
+
+```python
+import asyncio
+from autogen_agentchat.agents import AssistantAgent
+from autogen_ext.models.openai import OpenAIChatCompletionClient
+from autogen_scavio import create_scavio_tools
+
+tools = create_scavio_tools()
+
+agent = AssistantAgent(
+    name="researcher",
+    model_client=OpenAIChatCompletionClient(model="gpt-5.5"),
+    tools=tools,
+    system_message="You are a research assistant with access to search tools.",
+)
+
+async def main():
+    result = await agent.run(task="What are the top AI agent frameworks in 2026?")
+    print(result.messages[-1].content)
+
+asyncio.run(main())
+```
+
+## Selective Tool Loading
+
+Load only the providers you need:
+
+```python
+# Only Google and Amazon tools
+tools = create_scavio_tools(providers=["google", "amazon"])
+
+# Only YouTube
+tools = create_scavio_tools(providers=["youtube"])
+
+# Individual tool factories
+from autogen_scavio import create_web_search_tool, create_amazon_search_tool
+
+web_tool = create_web_search_tool(max_results=10)
+amazon_tool = create_amazon_search_tool(max_results=5)
+```
+
+## Available Tools
+
+| Provider | Tool | Description |
+|----------|------|-------------|
+| Google | `scavio_web_search` | Web search with knowledge graphs and related questions |
+| Amazon | `scavio_amazon_search` | Product search across 20+ marketplaces |
+| Amazon | `scavio_amazon_product` | Product details by ASIN |
+| YouTube | `scavio_youtube_search` | Video search with filters |
+| YouTube | `scavio_youtube_metadata` | Video metadata by ID |
+| Walmart | `scavio_walmart_search` | Product search with price/fulfillment filters |
+| Walmart | `scavio_walmart_product` | Product details by ID |
+| Reddit | `scavio_reddit_search` | Post and comment search |
+| Reddit | `scavio_reddit_post` | Post metadata and comments by URL |
+| TikTok | `scavio_tiktok_profile` | User profile lookup |
+| TikTok | `scavio_tiktok_user_posts` | User's posted videos |
+| TikTok | `scavio_tiktok_video` | Video details |
+| TikTok | `scavio_tiktok_video_comments` | Video comments |
+| TikTok | `scavio_tiktok_comment_replies` | Comment replies |
+| TikTok | `scavio_tiktok_search_videos` | Video search by keyword |
+| TikTok | `scavio_tiktok_search_users` | User search by keyword |
+| TikTok | `scavio_tiktok_hashtag` | Hashtag info |
+| TikTok | `scavio_tiktok_hashtag_videos` | Videos by hashtag |
+| TikTok | `scavio_tiktok_user_followers` | User's followers |
+| TikTok | `scavio_tiktok_user_followings` | User's followings |
+
+## Configuration
+
+```python
+from autogen_scavio import configure
+
+# Set API key programmatically
+configure(api_key="sk_live_...")
+
+# Or pass to factory
+tools = create_scavio_tools(api_key="sk_live_...", max_results=10)
+```

autogen_scavio-0.1.0/README.md

@@ -0,0 +1,96 @@
+# autogen-scavio
+
+AutoGen integration for the [Scavio Search API](https://scavio.dev). Provides 20 search tools across Google, Amazon, Walmart, YouTube, Reddit, and TikTok for use with AutoGen AI agents.
+
+## Installation
+
+```bash
+pip install autogen-scavio
+```
+
+## Setup
+
+Get a free API key at [dashboard.scavio.dev](https://dashboard.scavio.dev) and set it as an environment variable:
+
+```bash
+export SCAVIO_API_KEY="sk_live_..."
+```
+
+## Quick Start
+
+```python
+import asyncio
+from autogen_agentchat.agents import AssistantAgent
+from autogen_ext.models.openai import OpenAIChatCompletionClient
+from autogen_scavio import create_scavio_tools
+
+tools = create_scavio_tools()
+
+agent = AssistantAgent(
+    name="researcher",
+    model_client=OpenAIChatCompletionClient(model="gpt-5.5"),
+    tools=tools,
+    system_message="You are a research assistant with access to search tools.",
+)
+
+async def main():
+    result = await agent.run(task="What are the top AI agent frameworks in 2026?")
+    print(result.messages[-1].content)
+
+asyncio.run(main())
+```
+
+## Selective Tool Loading
+
+Load only the providers you need:
+
+```python
+# Only Google and Amazon tools
+tools = create_scavio_tools(providers=["google", "amazon"])
+
+# Only YouTube
+tools = create_scavio_tools(providers=["youtube"])
+
+# Individual tool factories
+from autogen_scavio import create_web_search_tool, create_amazon_search_tool
+
+web_tool = create_web_search_tool(max_results=10)
+amazon_tool = create_amazon_search_tool(max_results=5)
+```
+
+## Available Tools
+
+| Provider | Tool | Description |
+|----------|------|-------------|
+| Google | `scavio_web_search` | Web search with knowledge graphs and related questions |
+| Amazon | `scavio_amazon_search` | Product search across 20+ marketplaces |
+| Amazon | `scavio_amazon_product` | Product details by ASIN |
+| YouTube | `scavio_youtube_search` | Video search with filters |
+| YouTube | `scavio_youtube_metadata` | Video metadata by ID |
+| Walmart | `scavio_walmart_search` | Product search with price/fulfillment filters |
+| Walmart | `scavio_walmart_product` | Product details by ID |
+| Reddit | `scavio_reddit_search` | Post and comment search |
+| Reddit | `scavio_reddit_post` | Post metadata and comments by URL |
+| TikTok | `scavio_tiktok_profile` | User profile lookup |
+| TikTok | `scavio_tiktok_user_posts` | User's posted videos |
+| TikTok | `scavio_tiktok_video` | Video details |
+| TikTok | `scavio_tiktok_video_comments` | Video comments |
+| TikTok | `scavio_tiktok_comment_replies` | Comment replies |
+| TikTok | `scavio_tiktok_search_videos` | Video search by keyword |
+| TikTok | `scavio_tiktok_search_users` | User search by keyword |
+| TikTok | `scavio_tiktok_hashtag` | Hashtag info |
+| TikTok | `scavio_tiktok_hashtag_videos` | Videos by hashtag |
+| TikTok | `scavio_tiktok_user_followers` | User's followers |
+| TikTok | `scavio_tiktok_user_followings` | User's followings |
+
+## Configuration
+
+```python
+from autogen_scavio import configure
+
+# Set API key programmatically
+configure(api_key="sk_live_...")
+
+# Or pass to factory
+tools = create_scavio_tools(api_key="sk_live_...", max_results=10)
+```

autogen_scavio-0.1.0/autogen_scavio/__init__.py

@@ -0,0 +1,115 @@
+"""AutoGen integration for Scavio Search API."""
+
+from __future__ import annotations
+
+from autogen_core.tools import FunctionTool
+
+from autogen_scavio._client import configure
+from autogen_scavio.tools.amazon import create_amazon_product_tool, create_amazon_search_tool
+from autogen_scavio.tools.google import create_web_search_tool
+from autogen_scavio.tools.reddit import create_reddit_post_tool, create_reddit_search_tool
+from autogen_scavio.tools.tiktok import (
+    create_tiktok_comment_replies_tool,
+    create_tiktok_hashtag_tool,
+    create_tiktok_hashtag_videos_tool,
+    create_tiktok_profile_tool,
+    create_tiktok_search_users_tool,
+    create_tiktok_search_videos_tool,
+    create_tiktok_user_followers_tool,
+    create_tiktok_user_followings_tool,
+    create_tiktok_user_posts_tool,
+    create_tiktok_video_comments_tool,
+    create_tiktok_video_tool,
+)
+from autogen_scavio.tools.walmart import create_walmart_product_tool, create_walmart_search_tool
+from autogen_scavio.tools.youtube import create_youtube_metadata_tool, create_youtube_search_tool
+
+__version__ = "0.1.0"
+
+_PROVIDER_MAP: dict[str, list] = {
+    "google": [create_web_search_tool],
+    "amazon": [create_amazon_search_tool, create_amazon_product_tool],
+    "youtube": [create_youtube_search_tool, create_youtube_metadata_tool],
+    "walmart": [create_walmart_search_tool, create_walmart_product_tool],
+    "reddit": [create_reddit_search_tool, create_reddit_post_tool],
+    "tiktok": [
+        create_tiktok_profile_tool,
+        create_tiktok_user_posts_tool,
+        create_tiktok_video_tool,
+        create_tiktok_video_comments_tool,
+        create_tiktok_comment_replies_tool,
+        create_tiktok_search_videos_tool,
+        create_tiktok_search_users_tool,
+        create_tiktok_hashtag_tool,
+        create_tiktok_hashtag_videos_tool,
+        create_tiktok_user_followers_tool,
+        create_tiktok_user_followings_tool,
+    ],
+}
+
+
+def create_scavio_tools(
+    api_key: str | None = None,
+    max_results: int = 5,
+    providers: list[str] | None = None,
+) -> list[FunctionTool]:
+    """Create Scavio search tools for AutoGen agents.
+
+    Args:
+        api_key: Scavio API key. If None, reads from SCAVIO_API_KEY env var.
+        max_results: Default maximum results for search tools.
+        providers: List of providers to include (e.g. ["google", "amazon"]).
+            Defaults to all providers.
+
+    Returns:
+        List of FunctionTool instances ready for use with AutoGen agents.
+    """
+    configure(api_key)
+
+    selected = providers or list(_PROVIDER_MAP.keys())
+    tools: list[FunctionTool] = []
+
+    for provider in selected:
+        factories = _PROVIDER_MAP.get(provider)
+        if not factories:
+            raise ValueError(
+                f"Unknown provider '{provider}'. "
+                f"Available: {', '.join(_PROVIDER_MAP.keys())}"
+            )
+        for factory in factories:
+            import inspect
+
+            sig = inspect.signature(factory)
+            kwargs: dict = {}
+            if "max_results" in sig.parameters:
+                kwargs["max_results"] = max_results
+            tools.append(factory(**kwargs))
+
+    return tools
+
+
+__all__ = [
+    "__version__",
+    "configure",
+    "create_scavio_tools",
+    "create_web_search_tool",
+    "create_amazon_search_tool",
+    "create_amazon_product_tool",
+    "create_youtube_search_tool",
+    "create_youtube_metadata_tool",
+    "create_walmart_search_tool",
+    "create_walmart_product_tool",
+    "create_reddit_search_tool",
+    "create_reddit_post_tool",
+    "create_tiktok_profile_tool",
+    "create_tiktok_user_posts_tool",
+    "create_tiktok_video_tool",
+    "create_tiktok_video_comments_tool",
+    "create_tiktok_comment_replies_tool",
+    "create_tiktok_search_videos_tool",
+    "create_tiktok_search_users_tool",
+    "create_tiktok_hashtag_tool",
+    "create_tiktok_hashtag_videos_tool",
+    "create_tiktok_user_followers_tool",
+    "create_tiktok_user_followings_tool",
+]

autogen_scavio-0.1.0/autogen_scavio/_client.py

@@ -0,0 +1,61 @@
+"""Scavio API client management for AutoGen tools."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+from scavio import AsyncScavioClient
+
+_async_client: AsyncScavioClient | None = None
+_configured_api_key: str | None = None
+
+
+def configure(api_key: str | None = None) -> None:
+    """Set the Scavio API key and reset cached clients."""
+    global _configured_api_key, _async_client
+    _configured_api_key = api_key
+    _async_client = None
+
+
+def get_async_client() -> AsyncScavioClient:
+    """Return a cached AsyncScavioClient, creating one if needed."""
+    global _async_client
+    if _async_client is None:
+        key = _configured_api_key or os.getenv("SCAVIO_API_KEY")
+        if not key:
+            raise ValueError(
+                "A Scavio API key is required. Provide it via "
+                "configure(api_key=...) or set the SCAVIO_API_KEY "
+                "environment variable. Get a free key at "
+                "https://dashboard.scavio.dev"
+            )
+        _async_client = AsyncScavioClient(api_key=key)
+    return _async_client
+
+
+def truncate_list(
+    raw: dict[str, Any],
+    path: list[str],
+    max_results: int,
+) -> dict[str, Any]:
+    """Truncate a nested list in the response dict.
+
+    path is a list of keys to traverse, e.g. ["data", "products"].
+    """
+    obj = raw
+    for key in path[:-1]:
+        obj = obj.get(key, {})
+        if not isinstance(obj, dict):
+            return raw
+    last = path[-1]
+    items = obj.get(last)
+    if isinstance(items, list) and len(items) > max_results:
+        obj[last] = items[:max_results]
+    return raw
+
+
+def format_response(raw: dict[str, Any]) -> str:
+    """Serialize a response dict to a JSON string."""
+    return json.dumps(raw, indent=2)

autogen_scavio-0.1.0/autogen_scavio/tools/__init__.py

@@ -0,0 +1 @@
+"""Scavio tool implementations for AutoGen."""

autogen_scavio-0.1.0/autogen_scavio/tools/amazon.py

@@ -0,0 +1,142 @@
+"""Scavio Amazon tools for AutoGen."""
+
+from __future__ import annotations
+
+from autogen_core.tools import FunctionTool
+
+from autogen_scavio._client import format_response, get_async_client, truncate_list
+
+
+def create_amazon_search_tool(
+    max_results: int = 5,
+    pages: int | None = None,
+    autoselect_variant: bool | None = None,
+) -> FunctionTool:
+    """Create an Amazon search tool with the given configuration."""
+
+    async def scavio_amazon_search(
+        query: str,
+        domain: str = "com",
+        sort_by: str | None = None,
+        start_page: int | None = None,
+        category_id: str | None = None,
+        merchant_id: str | None = None,
+        language: str | None = None,
+        currency: str | None = None,
+        device: str | None = None,
+        zip_code: str | None = None,
+    ) -> str:
+        """Search Amazon product listings using the Scavio API.
+
+        Args:
+            query: The product search query.
+            domain: Amazon domain suffix (e.g. "com", "co.uk", "de").
+            sort_by: Sort order for results.
+            start_page: Page number to start from.
+            category_id: Filter by Amazon category ID.
+            merchant_id: Filter by merchant/seller ID.
+            language: Language code for results.
+            currency: Currency code for prices.
+            device: Device type for the request.
+            zip_code: ZIP code for localized pricing/availability.
+
+        Returns:
+            JSON string with product names, prices, ratings, ASINs,
+            and availability.
+        """
+        client = get_async_client()
+
+        params: dict = {
+            "query": query,
+            "domain": domain,
+        }
+        if sort_by is not None:
+            params["sort_by"] = sort_by
+        if start_page is not None:
+            params["start_page"] = start_page
+        if pages is not None:
+            params["pages"] = pages
+        if category_id is not None:
+            params["category_id"] = category_id
+        if merchant_id is not None:
+            params["merchant_id"] = merchant_id
+        if language is not None:
+            params["language"] = language
+        if currency is not None:
+            params["currency"] = currency
+        if device is not None:
+            params["device"] = device
+        if zip_code is not None:
+            params["zip_code"] = zip_code
+        if autoselect_variant is not None:
+            params["autoselect_variant"] = autoselect_variant
+
+        raw = await client.amazon.search(**params)
+
+        truncate_list(raw, ["data", "products"], max_results)
+
+        return format_response(raw)
+
+    return FunctionTool(
+        scavio_amazon_search,
+        description=(
+            "Search Amazon product listings. Returns product names, "
+            "prices, ratings, ASINs, and availability."
+        ),
+    )
+
+
+def create_amazon_product_tool() -> FunctionTool:
+    """Create an Amazon product detail tool."""
+
+    async def scavio_amazon_product(
+        asin: str,
+        domain: str = "com",
+        language: str | None = None,
+        currency: str | None = None,
+        device: str | None = None,
+        zip_code: str | None = None,
+        autoselect_variant: bool | None = None,
+    ) -> str:
+        """Fetch full details for a specific Amazon product by ASIN code.
+
+        Args:
+            asin: The Amazon Standard Identification Number for the product.
+            domain: Amazon domain suffix (e.g. "com", "co.uk", "de").
+            language: Language code for the response.
+            currency: Currency code for prices.
+            device: Device type for the request.
+            zip_code: ZIP code for localized pricing/availability.
+            autoselect_variant: Whether to auto-select the default variant.
+
+        Returns:
+            JSON string with full product details including title,
+            description, pricing, images, and specifications.
+        """
+        client = get_async_client()
+
+        params: dict = {
+            "asin": asin,
+            "domain": domain,
+        }
+        if language is not None:
+            params["language"] = language
+        if currency is not None:
+            params["currency"] = currency
+        if device is not None:
+            params["device"] = device
+        if zip_code is not None:
+            params["zip_code"] = zip_code
+        if autoselect_variant is not None:
+            params["autoselect_variant"] = autoselect_variant
+
+        raw = await client.amazon.product(**params)
+
+        return format_response(raw)
+
+    return FunctionTool(
+        scavio_amazon_product,
+        description=(
+            "Fetch full details for a specific Amazon product by ASIN code."
+        ),
+    )