langchain-channel3 0.1.0__tar.gz

langchain_channel3-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/

langchain_channel3-0.1.0/LICENSE

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

langchain_channel3-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.5
+Name: langchain-channel3
+Version: 0.1.0
+Summary: Channel3 product search tools for LangChain: search 100M+ products and compare live retailer offers.
+Project-URL: Homepage, https://channel3.ai/docs/langchain
+Project-URL: Documentation, https://channel3.ai/docs/langchain
+Project-URL: Source Code, https://github.com/channel3-ai/langchain-channel3
+Project-URL: repository, https://github.com/channel3-ai/langchain-channel3
+Author-email: Channel3 <support@trychannel3.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,channel3,ecommerce,langchain,product-search,shopping,tools
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: <4.0,>=3.10
+Requires-Dist: channel3-sdk<5.0.0,>=4.8.0
+Requires-Dist: langchain-core<2.0.0,>=1.0.0
+Description-Content-Type: text/markdown
+
+# langchain-channel3
+
+[Channel3](https://channel3.ai) product search tools for [LangChain](https://python.langchain.com). Give your agent search across 100M+ products from thousands of retailers, with every retailer's offer and live price.
+
+## Installation
+
+```bash
+pip install -U langchain-channel3
+```
+
+Set `CHANNEL3_API_KEY` in your environment. [Create a free API key](https://channel3.ai/sign-up/developer): every account gets 1,000 free credits a month. A search uses one credit; product details by ID are free, and each retailer URL lookup uses one credit.
+
+## Usage
+
+```python
+from langchain.agents import create_agent
+from langchain_channel3 import channel3_tools
+
+agent = create_agent(
+    model="anthropic:claude-sonnet-5-5",
+    tools=channel3_tools(),
+)
+
+result = agent.invoke(
+    {
+        "messages": [
+            {
+                "role": "user",
+                "content": "Find me a leather golf glove under $40 and tell me which retailer has it cheapest.",
+            }
+        ]
+    }
+)
+print(result["messages"][-1].content)
+```
+
+## Tools
+
+### `Channel3SearchProducts` (`search_products`)
+
+Searches for one product type and returns in-stock products, each with up to two images and every retailer's offer.
+
+- `query`: one product type and its constraints in natural language, such as `"red leather jacket under $200"`.
+- `image_url`: a public image URL for visual search. Combine it with `query` for text plus image.
+
+At least one is required.
+
+### `Channel3GetProducts` (`get_products`)
+
+Gets full product data (description, attributes, variants, images and offers) for up to 40 products in parallel.
+
+- `product_ids`: product IDs from `search_products`, or retailer product URLs.
+
+Inputs that can't be resolved are listed in `unresolved`. The call fails only when none resolve.
+
+Both tools use `response_format="content_and_artifact"`. For `search_products` the model sees one line per product with title, brand, best price and ID; for `get_products` it sees JSON. The full structured result is on the `ToolMessage` as `artifact`, so your UI can render product cards from it.
+
+Offer URLs are Channel3 buy links, so purchases earn affiliate commission for the API key's account.
+
+## Options
+
+```python
+from langchain_channel3 import Channel3Toolkit
+
+tools = Channel3Toolkit(api_key="...", conversation_id=chat_id, limit=12).get_tools()
+```
+
+The tool classes take the same options individually, for example `Channel3SearchProducts(limit=12)`.
+
+| Option | Description |
+| --- | --- |
+| `api_key` | Channel3 API key. Defaults to `CHANNEL3_API_KEY`. |
+| `conversation_id` | Groups one chat's calls together in your Channel3 analytics. |
+| `limit` | Products per search, from 1 to 30. Defaults to 8. Search tool only. |
+| `base_url` | Overrides the API base URL. |
+
+`channel3_tools(**options)` is shorthand for `Channel3Toolkit(**options).get_tools()`.
+
+## Errors
+
+API errors go back to the model as the tool result, for example "Channel3 rejected the API key" or "The Channel3 account is out of credits", so the agent can explain the problem instead of crashing the run. Pass `handle_tool_error=False` to a tool to raise them as `ToolException` instead.
+
+## Links
+
+- [Channel3 docs](https://channel3.ai/docs)
+- [TypeScript version](https://github.com/channel3-ai/agent-toolkit) for LangChain.js, the Vercel AI SDK and Mastra
+- [Channel3 Python SDK](https://pypi.org/project/channel3-sdk/) for the rest of the API
+
+## License
+
+MIT

langchain_channel3-0.1.0/README.md

@@ -0,0 +1,91 @@
+# langchain-channel3
+
+[Channel3](https://channel3.ai) product search tools for [LangChain](https://python.langchain.com). Give your agent search across 100M+ products from thousands of retailers, with every retailer's offer and live price.
+
+## Installation
+
+```bash
+pip install -U langchain-channel3
+```
+
+Set `CHANNEL3_API_KEY` in your environment. [Create a free API key](https://channel3.ai/sign-up/developer): every account gets 1,000 free credits a month. A search uses one credit; product details by ID are free, and each retailer URL lookup uses one credit.
+
+## Usage
+
+```python
+from langchain.agents import create_agent
+from langchain_channel3 import channel3_tools
+
+agent = create_agent(
+    model="anthropic:claude-sonnet-5-5",
+    tools=channel3_tools(),
+)
+
+result = agent.invoke(
+    {
+        "messages": [
+            {
+                "role": "user",
+                "content": "Find me a leather golf glove under $40 and tell me which retailer has it cheapest.",
+            }
+        ]
+    }
+)
+print(result["messages"][-1].content)
+```
+
+## Tools
+
+### `Channel3SearchProducts` (`search_products`)
+
+Searches for one product type and returns in-stock products, each with up to two images and every retailer's offer.
+
+- `query`: one product type and its constraints in natural language, such as `"red leather jacket under $200"`.
+- `image_url`: a public image URL for visual search. Combine it with `query` for text plus image.
+
+At least one is required.
+
+### `Channel3GetProducts` (`get_products`)
+
+Gets full product data (description, attributes, variants, images and offers) for up to 40 products in parallel.
+
+- `product_ids`: product IDs from `search_products`, or retailer product URLs.
+
+Inputs that can't be resolved are listed in `unresolved`. The call fails only when none resolve.
+
+Both tools use `response_format="content_and_artifact"`. For `search_products` the model sees one line per product with title, brand, best price and ID; for `get_products` it sees JSON. The full structured result is on the `ToolMessage` as `artifact`, so your UI can render product cards from it.
+
+Offer URLs are Channel3 buy links, so purchases earn affiliate commission for the API key's account.
+
+## Options
+
+```python
+from langchain_channel3 import Channel3Toolkit
+
+tools = Channel3Toolkit(api_key="...", conversation_id=chat_id, limit=12).get_tools()
+```
+
+The tool classes take the same options individually, for example `Channel3SearchProducts(limit=12)`.
+
+| Option | Description |
+| --- | --- |
+| `api_key` | Channel3 API key. Defaults to `CHANNEL3_API_KEY`. |
+| `conversation_id` | Groups one chat's calls together in your Channel3 analytics. |
+| `limit` | Products per search, from 1 to 30. Defaults to 8. Search tool only. |
+| `base_url` | Overrides the API base URL. |
+
+`channel3_tools(**options)` is shorthand for `Channel3Toolkit(**options).get_tools()`.
+
+## Errors
+
+API errors go back to the model as the tool result, for example "Channel3 rejected the API key" or "The Channel3 account is out of credits", so the agent can explain the problem instead of crashing the run. Pass `handle_tool_error=False` to a tool to raise them as `ToolException` instead.
+
+## Links
+
+- [Channel3 docs](https://channel3.ai/docs)
+- [TypeScript version](https://github.com/channel3-ai/agent-toolkit) for LangChain.js, the Vercel AI SDK and Mastra
+- [Channel3 Python SDK](https://pypi.org/project/channel3-sdk/) for the rest of the API
+
+## License
+
+MIT

langchain_channel3-0.1.0/langchain_channel3/__init__.py

@@ -0,0 +1,28 @@
+"""Channel3 product search tools for LangChain."""
+
+from typing import Any
+
+from langchain_core.tools import BaseTool
+
+from langchain_channel3.toolkit import Channel3Toolkit
+from langchain_channel3.tools import (
+    Channel3GetProducts,
+    Channel3SearchProducts,
+    GetProductsInput,
+    SearchProductsInput,
+)
+
+
+def channel3_tools(**kwargs: Any) -> list[BaseTool]:
+    """Both Channel3 tools, sharing the options ``Channel3Toolkit`` accepts."""
+    return Channel3Toolkit(**kwargs).get_tools()
+
+
+__all__ = [
+    "Channel3GetProducts",
+    "Channel3SearchProducts",
+    "Channel3Toolkit",
+    "GetProductsInput",
+    "SearchProductsInput",
+    "channel3_tools",
+]

langchain_channel3-0.1.0/langchain_channel3/_format.py

@@ -0,0 +1,107 @@
+"""Shapes Channel3 SDK products into compact, JSON-safe dicts for agents."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from channel3_sdk.types.product import Product
+
+CDN_IMAGE_PREFIX = "https://cdn.trychannel3.com/"
+
+
+def _cdn_images(product: Product) -> list[dict[str, Any]]:
+    return [
+        image.model_dump(exclude_none=True)
+        for image in product.images or []
+        if image.url.startswith(CDN_IMAGE_PREFIX)
+    ]
+
+
+def _with_cleaned_url(image: dict[str, Any]) -> dict[str, Any]:
+    cleaned = image.get("cleaned_url")
+    return {**image, "url": cleaned} if cleaned else image
+
+
+def _summary_images(product: Product) -> list[dict[str, Any]]:
+    """Up to two display images: the background-removed or main image first, then one other."""
+    images = _cdn_images(product)
+    primary_source = (
+        next((i for i in images if i.get("cleaned_url")), None)
+        or next((i for i in images if i.get("is_main_image")), None)
+        or (images[0] if images else None)
+    )
+    if primary_source is None:
+        return []
+    primary = _with_cleaned_url(primary_source)
+    second = next(
+        (
+            i
+            for i in images
+            if i is not primary_source
+            and i["url"] != primary["url"]
+            and i.get("cleaned_url") != primary["url"]
+        ),
+        None,
+    )
+    return [primary, _with_cleaned_url(second)] if second else [primary]
+
+
+def _offers(product: Product) -> list[dict[str, Any]]:
+    return [
+        offer.model_dump(mode="json", exclude_none=True, exclude={"max_commission_rate"})
+        for offer in product.offers or []
+    ]
+
+
+def product_summary(product: Product) -> dict[str, Any]:
+    return {
+        "id": product.id,
+        "title": product.title,
+        "brands": [
+            brand.model_dump(mode="json", exclude_none=True) for brand in product.brands or []
+        ],
+        "images": _summary_images(product),
+        "offers": _offers(product),
+    }
+
+
+def product_detail(product: Product) -> dict[str, Any]:
+    detail = product.model_dump(mode="json", exclude_none=True, exclude={"images", "offers"})
+    detail["images"] = _cdn_images(product)[:5]
+    detail["offers"] = _offers(product)
+    return detail
+
+
+def _lead_offer(offers: list[dict[str, Any]]) -> dict[str, Any] | None:
+    """The lowest-priced in-stock offer, or the lowest-priced offer when none are in stock."""
+    by_price = sorted(offers, key=lambda offer: offer["price"]["price"])
+    return next((o for o in by_price if o.get("availability") == "InStock"), None) or (
+        by_price[0] if by_price else None
+    )
+
+
+def _format_price(amount: float, currency: str) -> str:
+    return f"${amount:,.2f}" if currency == "USD" else f"{currency} {amount:,.2f}"
+
+
+def product_line(product: dict[str, Any]) -> str:
+    """One line for the model: title, brands, best price and retailer, and the ID."""
+    parts = [f'"{product["title"]}"']
+    brands = ", ".join(brand["name"] for brand in product.get("brands") or [])
+    if brands:
+        parts.append(brands)
+    best = _lead_offer(product.get("offers") or [])
+    if best:
+        parts.append(
+            f"{_format_price(best['price']['price'], best['price']['currency'])} at {best['domain']}"
+        )
+    return f"- {' — '.join(parts)} [id: {product['id']}]"
+
+
+def summarize_search(
+    query: str | None, image_url: str | None, products: list[dict[str, Any]]
+) -> str:
+    what = f' for "{query}"' if query else " for the image" if image_url else ""
+    return "\n".join(
+        [f"Found {len(products)} products{what}.", *(product_line(p) for p in products)]
+    )

langchain_channel3-0.1.0/langchain_channel3/toolkit.py

@@ -0,0 +1,43 @@
+"""Both Channel3 tools with shared options."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from langchain_core.tools import BaseTool, BaseToolkit
+from pydantic import Field, SecretStr
+
+from langchain_channel3.tools import Channel3GetProducts, Channel3SearchProducts
+
+
+class Channel3Toolkit(BaseToolkit):
+    """Channel3 product search and product detail tools.
+
+    Setup:
+        Install ``langchain-channel3`` and set ``CHANNEL3_API_KEY``.
+
+    Instantiate:
+        .. code-block:: python
+
+            from langchain_channel3 import Channel3Toolkit
+
+            toolkit = Channel3Toolkit(conversation_id=chat_id)
+            tools = toolkit.get_tools()
+    """
+
+    api_key: Optional[SecretStr] = Field(default=None, exclude=True)
+    """Channel3 API key. Defaults to the ``CHANNEL3_API_KEY`` environment variable."""
+    base_url: Optional[str] = None
+    """Overrides the API base URL."""
+    conversation_id: Optional[str] = None
+    """Groups one chat's calls together in your Channel3 analytics."""
+    limit: int = Field(default=8, ge=1, le=30)
+    """Maximum products per search."""
+
+    def get_tools(self) -> list[BaseTool]:
+        shared = {
+            "api_key": self.api_key,
+            "base_url": self.base_url,
+            "conversation_id": self.conversation_id,
+        }
+        return [Channel3SearchProducts(**shared, limit=self.limit), Channel3GetProducts(**shared)]