Unsplash API Tool for Real Photo Retrieval

[Jesse1786]

Checked

• I searched existing ideas and did not find a similar one
• I added a very descriptive title
• I've clearly described the feature request and motivation for it

Feature request

We'd like to add a toolkit to integrate the Unsplash API into LangChain. This would allow users to:

• Get royalty-free, real images on demand based on specific keywords or topics
• Access the metadata of retrieved images, such as the author, dimensions, and download link
• Filter images by categories, orientation, and popularity

Sample Usage

from langchain_community.tools import UnspashQueryRun
from langchain_community.utilities import UnsplashAPIWrapper

unsplash = UnsplashQueryRun(api_wrapper=UnsplashAPIWrapper())

unsplash.run("mountain")

Sample Output

https://images.unsplash.com/photo-1480497490787-505ec076689f?q=80&w=2069&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D

Motivation

Many projects require real, authentic images. Currently, LangChain doesn’t offer a way to retrieve real images on demand. By integrating Unsplash, which has a huge collection of real photos, this toolkit would make it easier for developers to add royalty-free images to their applications.

Proposal (If applicable)

We plan to create a tool that enables LangChain agents to access the Unsplash API. The additions would be unobtrusive and follow a format similar to existing files.

New Files

• libs/community/langchain_community/utilities/unsplash.py : API wrapper
• libs/community/langchain_community/tools/unsplash.py : Tool
• /libs/community/tests/unit_tests/tools/unsplash/
• /libs/community/tests/integration_tests/utilities/

Files to Modify

• libs/community/langchain_community/agent_toolkits/load_tools.py
• libs/community/langchain_community/tools/__init__.py
• libs/langchain/langchain/tools/__init__.py

Sample Code

class UnsplashQueryRun(BaseTool):
    """Tool that searches the Unsplash API."""

    name: str = "Unsplash"
    description: str = (
        "Query run for UnsplashAPI"
    )
    api_wrapper: UnsplashAPIWrapper

    args_schema: Type[BaseModel] = UnsplashQuery

    def _run(
        self,
        query: str,
        run_manager: Optional[CallbackManagerForToolRun] = None,
    ) -> str:
        """Uses the UnsplashAPIWrapper to perform the actual search."""
        return self.api_wrapper.run(query) 

class UnsplashAPIWrapper(BaseModel):
    top_k_results: int = 3
    load_all_available_meta: bool = False

    @model_validator(mode="before")
    @classmethod
    def validate_environment(cls, values: Dict) -> Any:
        """Validate that the python package exists in environment and also validates if the Unsplash API key exists"""
        try:
            #import unsplash-python in your environment
            
        except ImportError:
            raise ImportError(
                #unable to install the package
            )
        unsplash_api_key = #retrieved through environment variables
        return unsplash_api_key

    def run(self, query: str) -> str:
        """Search for the image and return it's url."""
        #we must see if the input is appropriate for searching Unsplash
        if !query.validate_input:
            return False
        
        #create url using api and queries in the form https://api.unsplash.com/photos/?client_id=API_KEY...
        
        #retrieves the results from the Unsplash API
        image_urls = requests.get(#request_url + params)
        
        final_results = []
        for url in image_urls[: self.top_k_results]:
            #we should check if it's a valid image url, if so we add it to final results
        if not final_results:
            return "No results were found"
        return final_results

About Us

We're a group of four students from the University of Toronto, and we're excited to contribute to LangChain. We like our idea because of its straightforward and practical use cases. We aim to have the first version ready by November, and we'd greatly appreciate any feedback or ideas!