langchain-pexafy 0.1.0__tar.gz

langchain_pexafy-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: pytest -q tests/unit_tests

langchain_pexafy-0.1.0/.gitignore

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

langchain_pexafy-0.1.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 — 2026-10-06
+
+First release: `PexafySearchPhotos`, `PexafyFindSimilarPhotos`, `PexafyGetPhoto`,
+`PexafyToolkit`. Sync and async, compact JSON content with the full records as the
+tool artifact, LangChain standard unit and integration tests.

langchain_pexafy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marouane Tijani
+
+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_pexafy-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.5
+Name: langchain-pexafy
+Version: 0.1.0
+Summary: LangChain tools for Pexafy: semantic search over 9M+ free stock photos from Unsplash, Pexels, Pixabay and more
+Project-URL: Homepage, https://pexafy.com
+Project-URL: Documentation, https://github.com/Pexafy/langchain-pexafy#readme
+Project-URL: Source, https://github.com/Pexafy/langchain-pexafy
+Project-URL: Issues, https://github.com/Pexafy/langchain-pexafy/issues
+Author-email: Marouane Tijani <marouane@pexafy.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,image search,langchain,langgraph,semantic search,stock photos,tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: pexafy>=0.1.1
+Provides-Extra: dev
+Requires-Dist: langchain-tests>=0.3; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# langchain-pexafy
+
+[LangChain](https://docs.langchain.com) and [LangGraph](https://docs.langchain.com/oss/python/langgraph/overview)
+tools for [Pexafy](https://pexafy.com): semantic search over 9M+ free stock photos
+from Unsplash, Pexels, Pixabay and six more libraries, behind one API. Your agent
+describes the picture it needs in plain English and gets back real photographs,
+each with its image URL, alt text, licence and the credit line to print.
+
+```bash
+pip install -U langchain-pexafy
+export PEXAFY_API_KEY="pexafy_api_..."
+```
+
+Get a key at [pexafy.com/dashboard/api-keys](https://pexafy.com/dashboard/api-keys/).
+The free plan gives 5,000 requests a month at 20 a minute; the key is issued
+immediately, with no card and no app review.
+
+## Tools
+
+| Tool | Name the model sees | What it does |
+|---|---|---|
+| `PexafySearchPhotos` | `pexafy_search_photos` | Search by describing the scene; optional `orientation` filter |
+| `PexafyFindSimilarPhotos` | `pexafy_find_similar_photos` | Photos that look like one already found, by `photo_id` |
+| `PexafyGetPhoto` | `pexafy_get_photo` | One photo's details and credit line, by `photo_id` |
+| `PexafyToolkit` | — | The three tools above, sharing one key |
+
+```python
+from langchain_pexafy import PexafySearchPhotos
+
+search = PexafySearchPhotos(max_results=3)
+print(search.invoke({"query": "a red bicycle leaning against a white wall"}))
+```
+
+Each photo comes back as a compact record, sized for a model's context:
+
+```json
+{
+  "rank": 1,
+  "photo_id": "019e1ea7-2e82-7a34-a451-4c6c7c8250f4",
+  "alt_text": "Red bicycle parked against white wall with front wheel facing left and back wheel right",
+  "url": "https://images.unsplash.com/photo-1520538254843-27a40bae5e3a?w=1280",
+  "thumbnail_url": "https://images.unsplash.com/photo-1520538254843-27a40bae5e3a?w=400",
+  "width": 4896,
+  "height": 3264,
+  "orientation": "landscape",
+  "dominant_color": "#CAB8B4",
+  "photographer": "Mitchel Lensink",
+  "source": "Unsplash",
+  "source_page_url": "https://unsplash.com/photos/red-bicycle-near-white-wall-Hx_dY7Xeszo",
+  "license": "free",
+  "credit": "Photo by Mitchel Lensink on Unsplash (https://pexafy.com/legal/licenses/#unsplash)"
+}
+```
+
+When an agent calls the tool, the `ToolMessage` content is that JSON list and its
+`artifact` holds the full API records (five image sizes, blur hash, HTML credit…),
+so your code can use them without spending the model's tokens.
+
+## In an agent
+
+`create_agent` runs on LangGraph:
+
+```python
+from langchain.agents import create_agent
+from langchain_pexafy import PexafyToolkit
+
+agent = create_agent(
+    "anthropic:claude-haiku-4-5",
+    tools=PexafyToolkit(max_results=4).get_tools(),
+    system_prompt="You illustrate articles. For each section, pick one photo, "
+                  "give its URL, alt text and the exact credit line.",
+)
+
+result = agent.invoke({"messages": [{
+    "role": "user",
+    "content": "Blog post 'A weekend in Lisbon': sections 'Trams', "
+               "'Pastéis de nata', 'Sunset at Miradouro'. One photo each.",
+}]})
+print(result["messages"][-1].content)
+```
+
+The tools work the same in a hand-built LangGraph graph (`ToolNode(tools)`) and
+in any model's `bind_tools(...)`. Every tool has an async path (`ainvoke`).
+
+## Writing queries
+
+Search runs on meaning, not keywords: `two people hiking on a ridge at dawn` ranks
+better than `hiking dawn people`. Describe what should be in the picture rather
+than what it is for. Leave `orientation` unset unless a shape is really needed: it
+removes every photo of another shape before ranking.
+
+The tool descriptions already tell the model this, so an agent writes good queries
+without help.
+
+## Errors
+
+Rate limits, exhausted quotas and unknown photo ids come back to the model as a
+short message it can act on (`handle_tool_error=True`). A missing key fails at
+construction, before any call. Set `handle_tool_error=False` to get the exception
+instead.
+
+## Credits and licences
+
+Photos are free to use under their library's licence; `license` and `source_page_url`
+say which. On the free plan, print the `credit` line next to each photo you
+publish. Pexafy finds existing photographs: it does not generate images.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/unit_tests                                  # offline
+PEXAFY_API_KEY=... pytest tests/integration_tests        # live API
+```
+
+Both suites are LangChain's standard tool tests (`langchain-tests`).
+
+## Links
+
+- [Pexafy API docs](https://docs.pexafy.com) · [Python SDK](https://github.com/Pexafy/pexafy-python) (`pip install pexafy`)
+- [Pexafy MCP server](https://github.com/Pexafy/pexafy-mcp) for MCP clients (`https://mcp.pexafy.com/mcp`)
+
+MIT licence.

langchain_pexafy-0.1.0/README.md

@@ -0,0 +1,123 @@
+# langchain-pexafy
+
+[LangChain](https://docs.langchain.com) and [LangGraph](https://docs.langchain.com/oss/python/langgraph/overview)
+tools for [Pexafy](https://pexafy.com): semantic search over 9M+ free stock photos
+from Unsplash, Pexels, Pixabay and six more libraries, behind one API. Your agent
+describes the picture it needs in plain English and gets back real photographs,
+each with its image URL, alt text, licence and the credit line to print.
+
+```bash
+pip install -U langchain-pexafy
+export PEXAFY_API_KEY="pexafy_api_..."
+```
+
+Get a key at [pexafy.com/dashboard/api-keys](https://pexafy.com/dashboard/api-keys/).
+The free plan gives 5,000 requests a month at 20 a minute; the key is issued
+immediately, with no card and no app review.
+
+## Tools
+
+| Tool | Name the model sees | What it does |
+|---|---|---|
+| `PexafySearchPhotos` | `pexafy_search_photos` | Search by describing the scene; optional `orientation` filter |
+| `PexafyFindSimilarPhotos` | `pexafy_find_similar_photos` | Photos that look like one already found, by `photo_id` |
+| `PexafyGetPhoto` | `pexafy_get_photo` | One photo's details and credit line, by `photo_id` |
+| `PexafyToolkit` | — | The three tools above, sharing one key |
+
+```python
+from langchain_pexafy import PexafySearchPhotos
+
+search = PexafySearchPhotos(max_results=3)
+print(search.invoke({"query": "a red bicycle leaning against a white wall"}))
+```
+
+Each photo comes back as a compact record, sized for a model's context:
+
+```json
+{
+  "rank": 1,
+  "photo_id": "019e1ea7-2e82-7a34-a451-4c6c7c8250f4",
+  "alt_text": "Red bicycle parked against white wall with front wheel facing left and back wheel right",
+  "url": "https://images.unsplash.com/photo-1520538254843-27a40bae5e3a?w=1280",
+  "thumbnail_url": "https://images.unsplash.com/photo-1520538254843-27a40bae5e3a?w=400",
+  "width": 4896,
+  "height": 3264,
+  "orientation": "landscape",
+  "dominant_color": "#CAB8B4",
+  "photographer": "Mitchel Lensink",
+  "source": "Unsplash",
+  "source_page_url": "https://unsplash.com/photos/red-bicycle-near-white-wall-Hx_dY7Xeszo",
+  "license": "free",
+  "credit": "Photo by Mitchel Lensink on Unsplash (https://pexafy.com/legal/licenses/#unsplash)"
+}
+```
+
+When an agent calls the tool, the `ToolMessage` content is that JSON list and its
+`artifact` holds the full API records (five image sizes, blur hash, HTML credit…),
+so your code can use them without spending the model's tokens.
+
+## In an agent
+
+`create_agent` runs on LangGraph:
+
+```python
+from langchain.agents import create_agent
+from langchain_pexafy import PexafyToolkit
+
+agent = create_agent(
+    "anthropic:claude-haiku-4-5",
+    tools=PexafyToolkit(max_results=4).get_tools(),
+    system_prompt="You illustrate articles. For each section, pick one photo, "
+                  "give its URL, alt text and the exact credit line.",
+)
+
+result = agent.invoke({"messages": [{
+    "role": "user",
+    "content": "Blog post 'A weekend in Lisbon': sections 'Trams', "
+               "'Pastéis de nata', 'Sunset at Miradouro'. One photo each.",
+}]})
+print(result["messages"][-1].content)
+```
+
+The tools work the same in a hand-built LangGraph graph (`ToolNode(tools)`) and
+in any model's `bind_tools(...)`. Every tool has an async path (`ainvoke`).
+
+## Writing queries
+
+Search runs on meaning, not keywords: `two people hiking on a ridge at dawn` ranks
+better than `hiking dawn people`. Describe what should be in the picture rather
+than what it is for. Leave `orientation` unset unless a shape is really needed: it
+removes every photo of another shape before ranking.
+
+The tool descriptions already tell the model this, so an agent writes good queries
+without help.
+
+## Errors
+
+Rate limits, exhausted quotas and unknown photo ids come back to the model as a
+short message it can act on (`handle_tool_error=True`). A missing key fails at
+construction, before any call. Set `handle_tool_error=False` to get the exception
+instead.
+
+## Credits and licences
+
+Photos are free to use under their library's licence; `license` and `source_page_url`
+say which. On the free plan, print the `credit` line next to each photo you
+publish. Pexafy finds existing photographs: it does not generate images.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/unit_tests                                  # offline
+PEXAFY_API_KEY=... pytest tests/integration_tests        # live API
+```
+
+Both suites are LangChain's standard tool tests (`langchain-tests`).
+
+## Links
+
+- [Pexafy API docs](https://docs.pexafy.com) · [Python SDK](https://github.com/Pexafy/pexafy-python) (`pip install pexafy`)
+- [Pexafy MCP server](https://github.com/Pexafy/pexafy-mcp) for MCP clients (`https://mcp.pexafy.com/mcp`)
+
+MIT licence.

langchain_pexafy-0.1.0/examples/agent.py

@@ -0,0 +1,28 @@
+"""An agent that illustrates a blog post outline with real, credited photos.
+
+    pip install langchain-pexafy langchain langchain-anthropic
+    export PEXAFY_API_KEY=... ANTHROPIC_API_KEY=...
+    python examples/agent.py
+"""
+
+from langchain.agents import create_agent
+
+from langchain_pexafy import PexafyToolkit
+
+agent = create_agent(
+    "anthropic:claude-haiku-4-5",
+    tools=PexafyToolkit(max_results=4).get_tools(),
+    system_prompt=(
+        "You illustrate articles. For each section, pick one photo, give its URL, "
+        "alt text and the exact credit line."
+    ),
+)
+
+result = agent.invoke({
+    "messages": [{
+        "role": "user",
+        "content": "Blog post 'A weekend in Lisbon': sections 'Trams', 'Pastéis de nata', "
+                   "'Sunset at Miradouro'. One photo each.",
+    }]
+})
+print(result["messages"][-1].content)

langchain_pexafy-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-pexafy"
+version = "0.1.0"
+description = "LangChain tools for Pexafy: semantic search over 9M+ free stock photos from Unsplash, Pexels, Pixabay and more"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{name = "Marouane Tijani", email = "marouane@pexafy.com"}]
+keywords = ["langchain", "langgraph", "agents", "tools", "stock photos", "image search", "semantic search"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Graphics",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = ["langchain-core>=0.3.0", "pexafy>=0.1.1"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-asyncio>=0.21", "langchain-tests>=0.3", "ruff>=0.5"]
+
+[project.urls]
+Homepage = "https://pexafy.com"
+Documentation = "https://github.com/Pexafy/langchain-pexafy#readme"
+Source = "https://github.com/Pexafy/langchain-pexafy"
+Issues = "https://github.com/Pexafy/langchain-pexafy/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/langchain_pexafy"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+ignore = ["UP007", "UP045"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

langchain_pexafy-0.1.0/src/langchain_pexafy/__init__.py

@@ -0,0 +1,21 @@
+"""LangChain tools for Pexafy: semantic search over free stock photos.
+
+```python
+from langchain_pexafy import PexafySearchPhotos
+
+PexafySearchPhotos().invoke({"query": "a quiet street in the rain"})
+```
+"""
+
+__version__ = "0.1.0"
+
+from .toolkit import PexafyToolkit
+from .tools import PexafyFindSimilarPhotos, PexafyGetPhoto, PexafySearchPhotos
+
+__all__ = [
+    "PexafySearchPhotos",
+    "PexafyFindSimilarPhotos",
+    "PexafyGetPhoto",
+    "PexafyToolkit",
+    "__version__",
+]

langchain_pexafy-0.1.0/src/langchain_pexafy/_format.py

@@ -0,0 +1,83 @@
+"""What the model reads of a photo.
+
+The API returns some thirty fields per photo, most of them for a page that renders
+the image (blur hash, five sizes, the long AI description). An agent needs far less:
+what the photo shows, where to fetch it, and the credit line it has to print next to
+it. Everything else stays in the tool's artifact, untouched.
+
+Two fields come from third parties — the photo's alt text and the photographer's
+name — and reach the model as text it will read, so they are flattened to one line,
+stripped of control and invisible characters, and capped.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from typing import Any
+
+from pexafy import Photo
+
+FREE_TEXT_MAX_LENGTH = 300
+
+# Words a source writes where it has no name: "Photo by Unknown on Pixabay", and a
+# missing surname stringified, "nympha57 None".
+_NO_NAME = {"unknown", "none", "null", "undefined", "n/a", "nan"}
+_CREDIT_LINE = re.compile(r"^(Photo) by (.*?)( on .*)$", re.S)
+
+
+def clean_text(value: Any, limit: int = FREE_TEXT_MAX_LENGTH) -> str:
+    """One line, no control or format character, at most `limit` characters."""
+    if not isinstance(value, str):
+        return ""
+    kept = [
+        " " if ch.isspace() else ch
+        for ch in value
+        if ch.isspace() or unicodedata.category(ch) not in {"Cc", "Cf", "Cs"}
+    ]
+    text = re.sub(r" {2,}", " ", "".join(kept)).strip()
+    if len(text) > limit:
+        text = text[: limit - 1].rstrip() + "…"
+    return text
+
+
+def clean_name(name: Any) -> str:
+    """A photographer's name without placeholder words; "" when nothing real is left."""
+    words = clean_text(name).split()
+    kept = [w for w in words if w.lower() not in _NO_NAME]
+    if len(kept) < len(words) and [w.lower() for w in kept] == ["photographer"]:
+        kept = []
+    cleaned = " ".join(kept)
+    return "" if cleaned.isdigit() else cleaned
+
+
+def clean_credit(line: str) -> str:
+    """'Photo by nympha57 None on Pexels' -> 'Photo by nympha57 on Pexels'."""
+    line = clean_text(line, limit=400)
+    match = _CREDIT_LINE.match(line)
+    if not match:
+        return line
+    lead, who, rest = match.groups()
+    who = clean_name(who)
+    return f"{lead} by {who}{rest}" if who else f"{lead}{rest}"
+
+
+def summarize(photo: Photo, rank: int) -> dict[str, Any]:
+    """The compact view of one photo that goes into the tool message."""
+    return {
+        "rank": rank,
+        "photo_id": photo.photo_id,
+        "alt_text": clean_text(photo.alt_text),
+        "url": photo.urls.regular or photo.image_url,
+        "thumbnail_url": photo.urls.small or photo.urls.thumb,
+        "width": photo.width,
+        "height": photo.height,
+        "orientation": photo.orientation,
+        "dominant_color": photo.color_hex,
+        "photographer": clean_name(photo.photographer_full_name)
+        or clean_name(photo.photographer_username),
+        "source": photo.source,
+        "source_page_url": photo.source_image_url,
+        "license": photo.license_type,
+        "credit": clean_credit(photo.attribution.plain),
+    }

langchain_pexafy-0.1.0/src/langchain_pexafy/toolkit.py

@@ -0,0 +1,34 @@
+"""All Pexafy tools at once, sharing one key."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from langchain_core.tools import BaseTool, BaseToolkit
+from pydantic import SecretStr
+
+from .tools import PexafyFindSimilarPhotos, PexafyGetPhoto, PexafySearchPhotos
+
+
+class PexafyToolkit(BaseToolkit):
+    """Search, find similar and get one photo.
+
+    ```python
+    from langchain_pexafy import PexafyToolkit
+
+    tools = PexafyToolkit().get_tools()  # reads PEXAFY_API_KEY
+    ```
+    """
+
+    api_key: Optional[SecretStr] = None
+    max_results: int = 6
+
+    def get_tools(self) -> list[BaseTool]:
+        kwargs = {"max_results": self.max_results}
+        if self.api_key is not None:
+            kwargs["api_key"] = self.api_key
+        return [
+            PexafySearchPhotos(**kwargs),
+            PexafyFindSimilarPhotos(**kwargs),
+            PexafyGetPhoto(**kwargs),
+        ]

langchain_pexafy-0.1.0/src/langchain_pexafy/tools.py

@@ -0,0 +1,292 @@
+"""LangChain tools for the Pexafy photo search API."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Literal, Optional
+
+import pexafy
+from langchain_core.callbacks import AsyncCallbackManagerForToolRun, CallbackManagerForToolRun
+from langchain_core.tools import BaseTool, ToolException
+from pydantic import BaseModel, ConfigDict, Field, PrivateAttr, SecretStr, model_validator
+
+from ._format import summarize
+
+__all__ = [
+    "PexafySearchPhotos",
+    "PexafyFindSimilarPhotos",
+    "PexafyGetPhoto",
+]
+
+Orientation = Literal["landscape", "portrait", "square"]
+
+QUERY_MAX_LENGTH = 250
+MAX_RESULTS = 20
+
+_QUERY_DESCRIPTION = (
+    "The photograph you want, as one concise English sentence about its visible "
+    "subject and scene, e.g. 'two colleagues laughing in a bright open-plan office'. "
+    "Full sentences rank better than keyword lists: the search matches meaning. "
+    "Describe what should be in the picture, not what it is for."
+)
+_ORIENTATION_DESCRIPTION = (
+    "Leave unset unless a shape is actually required (a wide banner: landscape; a "
+    "phone wallpaper or a vertical story: portrait). It is a hard filter that drops "
+    "every photo of another shape before ranking, so setting it without need loses "
+    "the best matches. Several values may be combined."
+)
+_COUNT_DESCRIPTION = f"How many photos to return, 1 to {MAX_RESULTS}."
+_PHOTO_ID_DESCRIPTION = (
+    "A Pexafy photo_id, as returned by a previous Pexafy search "
+    "(e.g. '019e1ecb-0039-7da6-b1ca-987ee4d337c0')."
+)
+
+
+class SearchPhotosInput(BaseModel):
+    query: str = Field(min_length=1, max_length=QUERY_MAX_LENGTH, description=_QUERY_DESCRIPTION)
+    orientation: Optional[list[Orientation]] = Field(
+        default=None, description=_ORIENTATION_DESCRIPTION
+    )
+    count: Optional[int] = Field(default=None, ge=1, le=MAX_RESULTS, description=_COUNT_DESCRIPTION)
+
+
+class FindSimilarPhotosInput(BaseModel):
+    photo_id: str = Field(min_length=1, description=_PHOTO_ID_DESCRIPTION)
+    count: Optional[int] = Field(default=None, ge=1, le=MAX_RESULTS, description=_COUNT_DESCRIPTION)
+
+
+class GetPhotoInput(BaseModel):
+    photo_id: str = Field(min_length=1, description=_PHOTO_ID_DESCRIPTION)
+
+
+class _PexafyTool(BaseTool):
+    """Holds the key and the clients; the subclasses only say what they call."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    api_key: Optional[SecretStr] = None
+    """Pexafy API key. Falls back to the `PEXAFY_API_KEY` environment variable."""
+
+    base_url: str = pexafy.DEFAULT_BASE_URL
+    max_results: int = Field(default=6, ge=1, le=MAX_RESULTS)
+    """How many photos a search returns when the model does not ask for a number."""
+
+    response_format: Literal["content", "content_and_artifact"] = "content_and_artifact"
+    handle_tool_error: bool = True
+    """Quota, rate-limit and not-found errors go back to the model as text it can act on."""
+
+    _client: Optional[pexafy.Client] = PrivateAttr(default=None)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _key_from_env(cls, values: Any) -> Any:
+        if isinstance(values, dict) and not values.get("api_key"):
+            key = os.environ.get("PEXAFY_API_KEY")
+            if key:
+                values = {**values, "api_key": key}
+        return values
+
+    @model_validator(mode="after")
+    def _require_key(self) -> _PexafyTool:
+        if self.api_key is None or not self.api_key.get_secret_value():
+            raise ValueError(
+                "No Pexafy API key. Pass api_key= or set PEXAFY_API_KEY. "
+                "Keys are created at https://pexafy.com/dashboard/api-keys/ "
+                "(free plan, no card)."
+            )
+        return self
+
+    def _client_kwargs(self) -> dict[str, Any]:
+        assert self.api_key is not None
+        return {"api_key": self.api_key.get_secret_value(), "base_url": self.base_url}
+
+    def _tag(self, client: Any) -> Any:
+        # Lets the API tell requests made through this package from direct SDK use.
+        from . import __version__
+
+        client._http.headers["user-agent"] = (
+            f"langchain-pexafy/{__version__} pexafy-python/{pexafy.__version__}"
+        )
+        return client
+
+    @property
+    def client(self) -> pexafy.Client:
+        if self._client is None:
+            self._client = self._tag(pexafy.Client(**self._client_kwargs()))
+        return self._client
+
+    def _async_client(self) -> pexafy.AsyncClient:
+        # One per call: an httpx.AsyncClient is bound to the event loop that made it.
+        return self._tag(pexafy.AsyncClient(**self._client_kwargs()))
+
+    @staticmethod
+    def _error(exc: pexafy.PexafyError) -> ToolException:
+        if isinstance(exc, pexafy.RateLimitError):
+            return ToolException(f"Pexafy rate limit or quota reached: {exc}")
+        if isinstance(exc, pexafy.NotFoundError):
+            return ToolException(f"No such Pexafy photo: {exc}")
+        return ToolException(f"Pexafy request failed: {exc}")
+
+    @staticmethod
+    def _photos(result: pexafy.SearchResult) -> tuple[str, list[dict[str, Any]]]:
+        photos = list(result.photos)
+        summary = [summarize(p, rank) for rank, p in enumerate(photos, start=1)]
+        if not summary:
+            return "No photos matched. Try describing the scene differently.", []
+        return json.dumps(summary, ensure_ascii=False), [p.raw for p in photos]
+
+
+class PexafySearchPhotos(_PexafyTool):
+    """Search free-to-use stock photos by describing the scene.
+
+    Setup:
+        ```bash
+        pip install -U langchain-pexafy
+        export PEXAFY_API_KEY="pexafy_api_..."
+        ```
+
+    Instantiate:
+        ```python
+        from langchain_pexafy import PexafySearchPhotos
+
+        tool = PexafySearchPhotos(max_results=5)
+        ```
+
+    Invoke directly with args:
+        ```python
+        tool.invoke({"query": "a red bicycle leaning against a white wall"})
+        ```
+
+    Invoke with a ToolCall (what an agent does): the message content is a JSON list
+    of compact photo records; `artifact` holds the full API records.
+    """
+
+    name: str = "pexafy_search_photos"
+    description: str = (
+        "Find real, free-to-use stock photographs (Unsplash, Pexels, Pixabay and other "
+        "libraries) by describing the scene in plain English. Use it whenever you need a "
+        "photo: a blog or article header, a hero image, an illustration for a section, a "
+        "slide or newsletter picture. It finds photographs that already exist; it does not "
+        "generate or edit images, and does not find illustrations, logos, icons or named "
+        "people. Each result has an image URL, alt text, its licence and the credit line "
+        "to print next to the photo."
+    )
+    args_schema: type[BaseModel] = SearchPhotosInput
+
+    def _filters(self, orientation: Optional[list[str]], count: Optional[int]) -> dict[str, Any]:
+        filters: dict[str, Any] = {"per_page": count or self.max_results}
+        if orientation:
+            filters["orientation"] = list(orientation)
+        return filters
+
+    def _run(
+        self,
+        query: str,
+        orientation: Optional[list[str]] = None,
+        count: Optional[int] = None,
+        run_manager: Optional[CallbackManagerForToolRun] = None,
+    ) -> tuple[str, list[dict[str, Any]]]:
+        try:
+            result = self.client.search(query, **self._filters(orientation, count))
+        except pexafy.PexafyError as exc:
+            raise self._error(exc) from exc
+        return self._photos(result)
+
+    async def _arun(
+        self,
+        query: str,
+        orientation: Optional[list[str]] = None,
+        count: Optional[int] = None,
+        run_manager: Optional[AsyncCallbackManagerForToolRun] = None,
+    ) -> tuple[str, list[dict[str, Any]]]:
+        try:
+            async with self._async_client() as client:
+                result = await client.search(query, **self._filters(orientation, count))
+        except pexafy.PexafyError as exc:
+            raise self._error(exc) from exc
+        return self._photos(result)
+
+
+class PexafyFindSimilarPhotos(_PexafyTool):
+    """Find photos that look like one already found.
+
+    ```python
+    from langchain_pexafy import PexafyFindSimilarPhotos
+
+    PexafyFindSimilarPhotos().invoke({"photo_id": "019e1ea7-2e82-7a34-a451-4c6c7c8250f4"})
+    ```
+    """
+
+    name: str = "pexafy_find_similar_photos"
+    description: str = (
+        "Find stock photographs that look like a photo returned by an earlier Pexafy "
+        "search: same subject, composition and mood. Use it to offer alternatives to a "
+        "photo that is close but not quite right, or to build a consistent set. Takes the "
+        "photo_id of that photo."
+    )
+    args_schema: type[BaseModel] = FindSimilarPhotosInput
+
+    def _run(
+        self,
+        photo_id: str,
+        count: Optional[int] = None,
+        run_manager: Optional[CallbackManagerForToolRun] = None,
+    ) -> tuple[str, list[dict[str, Any]]]:
+        try:
+            result = self.client.similar(photo_id, per_page=count or self.max_results)
+        except pexafy.PexafyError as exc:
+            raise self._error(exc) from exc
+        return self._photos(result)
+
+    async def _arun(
+        self,
+        photo_id: str,
+        count: Optional[int] = None,
+        run_manager: Optional[AsyncCallbackManagerForToolRun] = None,
+    ) -> tuple[str, list[dict[str, Any]]]:
+        try:
+            async with self._async_client() as client:
+                result = await client.similar(photo_id, per_page=count or self.max_results)
+        except pexafy.PexafyError as exc:
+            raise self._error(exc) from exc
+        return self._photos(result)
+
+
+class PexafyGetPhoto(_PexafyTool):
+    """Fetch one photo's details and credit line by its photo_id.
+
+    ```python
+    from langchain_pexafy import PexafyGetPhoto
+
+    PexafyGetPhoto().invoke({"photo_id": "019e1ea7-2e82-7a34-a451-4c6c7c8250f4"})
+    ```
+    """
+
+    name: str = "pexafy_get_photo"
+    description: str = (
+        "Get the details of one Pexafy photo by its photo_id: image URL, size, alt text, "
+        "licence and the credit line to print next to it."
+    )
+    args_schema: type[BaseModel] = GetPhotoInput
+
+    @staticmethod
+    def _one(photo: pexafy.Photo) -> tuple[str, dict[str, Any]]:
+        return json.dumps(summarize(photo, 1), ensure_ascii=False), photo.raw
+
+    def _run(
+        self, photo_id: str, run_manager: Optional[CallbackManagerForToolRun] = None
+    ) -> tuple[str, dict[str, Any]]:
+        try:
+            return self._one(self.client.get_photo(photo_id))
+        except pexafy.PexafyError as exc:
+            raise self._error(exc) from exc
+
+    async def _arun(
+        self, photo_id: str, run_manager: Optional[AsyncCallbackManagerForToolRun] = None
+    ) -> tuple[str, dict[str, Any]]:
+        try:
+            async with self._async_client() as client:
+                return self._one(await client.get_photo(photo_id))
+        except pexafy.PexafyError as exc:
+            raise self._error(exc) from exc

langchain_pexafy-0.1.0/tests/integration_tests/test_standard.py

@@ -0,0 +1,47 @@
+"""LangChain's standard integration tests, against the live API.
+
+Needs PEXAFY_API_KEY; skipped without it.
+"""
+
+import os
+
+import pytest
+from langchain_tests.integration_tests import ToolsIntegrationTests
+
+from langchain_pexafy import PexafyFindSimilarPhotos, PexafyGetPhoto, PexafySearchPhotos
+
+pytestmark = pytest.mark.skipif(
+    not os.environ.get("PEXAFY_API_KEY"), reason="PEXAFY_API_KEY not set"
+)
+
+PHOTO_ID = "019e1ea7-2e82-7a34-a451-4c6c7c8250f4"
+
+
+class TestSearchPhotosIntegration(ToolsIntegrationTests):
+    @property
+    def tool_constructor(self):
+        return PexafySearchPhotos
+
+    @property
+    def tool_invoke_params_example(self):
+        return {"query": "a red bicycle leaning against a white wall", "count": 2}
+
+
+class TestFindSimilarPhotosIntegration(ToolsIntegrationTests):
+    @property
+    def tool_constructor(self):
+        return PexafyFindSimilarPhotos
+
+    @property
+    def tool_invoke_params_example(self):
+        return {"photo_id": PHOTO_ID, "count": 2}
+
+
+class TestGetPhotoIntegration(ToolsIntegrationTests):
+    @property
+    def tool_constructor(self):
+        return PexafyGetPhoto
+
+    @property
+    def tool_invoke_params_example(self):
+        return {"photo_id": PHOTO_ID}

langchain_pexafy-0.1.0/tests/unit_tests/test_standard.py

@@ -0,0 +1,53 @@
+"""LangChain's standard unit tests, for each tool."""
+
+from langchain_tests.unit_tests import ToolsUnitTests
+
+from langchain_pexafy import PexafyFindSimilarPhotos, PexafyGetPhoto, PexafySearchPhotos
+
+PHOTO_ID = "019e1ea7-2e82-7a34-a451-4c6c7c8250f4"
+
+
+class TestSearchPhotosUnit(ToolsUnitTests):
+    @property
+    def tool_constructor(self):
+        return PexafySearchPhotos
+
+    @property
+    def tool_constructor_params(self):
+        return {"api_key": "pexafy_api_test"}
+
+    @property
+    def tool_invoke_params_example(self):
+        return {"query": "a red bicycle leaning against a white wall", "count": 3}
+
+    @property
+    def init_from_env_params(self):
+        return {"PEXAFY_API_KEY": "pexafy_api_env"}, {}, {"api_key": "pexafy_api_env"}
+
+
+class TestFindSimilarPhotosUnit(ToolsUnitTests):
+    @property
+    def tool_constructor(self):
+        return PexafyFindSimilarPhotos
+
+    @property
+    def tool_constructor_params(self):
+        return {"api_key": "pexafy_api_test"}
+
+    @property
+    def tool_invoke_params_example(self):
+        return {"photo_id": PHOTO_ID, "count": 3}
+
+
+class TestGetPhotoUnit(ToolsUnitTests):
+    @property
+    def tool_constructor(self):
+        return PexafyGetPhoto
+
+    @property
+    def tool_constructor_params(self):
+        return {"api_key": "pexafy_api_test"}
+
+    @property
+    def tool_invoke_params_example(self):
+        return {"photo_id": PHOTO_ID}