Defining Custom Tools Documentation improvement (API integration)

[solyarisoftware]

Hi Harrison, all,
Langchain is a great project!

I'm trying to implement custom APIs integration as langchain tool, as you suggested on discord, but is not clear exactly how it works.

Documentation about Defining Custom Tools is not fully clear to me. Docs lacks a straightforward example of creating a new tool from scratch. Improvement in the documentation would very useful.

As far as I understand, a Tool is just an instance of the Tool dataclass. Given some function that take a string an return a string. But how can I integrate a custom function as a tool instance?

BTW as a simple demo example, say I'd like to integrate a function that returns weather forecasts given a location and time period, like this:

weather(where='Genova, Italy', when='today')
# => in Genova, Italy, today is sunny! Temperature is 20 degrees Celsius.

---

In detail, suppose I have a custom Python function (a custom API) that report weather forecasts, something like this mockup:

#  weather_mockup.py
def weather(where: str = None, when: str = None) -> str:
    '''
    given a location and a time period,
    return weather forecast description in natural language (english)

    parameters:
        where: location
        when: time period

    returns:
        weather forecast description
    '''
    if where and when:
        return f'in {where}, {when} is sunny! Temperature is 20 degrees Celsius.'
    elif not where:
        return 'where?'
    elif not when:
        return 'when?'
    else:
        return 'I don\'t know'


if __name__ == '__main__':
    print(weather(where='Genova, Italy', when='today'))
    # => in Genova, Italy, today is sunny! Temperature is 20 degrees Celsius.

So, as far as I understand, I need to wrap this function as a langchain tool. Is the following implementation correct?

# weather_tool.py
from weather_mockup import weather

def weather_tool(when_and_where: str) -> str:
    '''
        input string where_and_when is a list of python string arguments
        with format as in the following example:

        "'arg 1' \"arg 2\" ... \"argN\""

        The weather function needs 2 arguments: where and when,
        so the when_and_where input string example could be:

        "'Genova, Italy' 'today'"
    '''

    # split the input string into a list of arguments
    pattern = r"(['\"])(.*?)\1"
    args = re.findall(pattern, input_str)
    args = [arg[1] for arg in args]

    # call the weather function passing arguments
    where = args[0]
    when = args[1]
    return weather(where, when)


tool = Tool(
    name='weather',
    func=weather_tool,
    description="helps to retrive weather forecast, given arguments: 'where' (the location) and 'when' (the data or time period)"
)

input_str = "'Genova, Italy' 'today'"
output_str = tool.func(input_str)
print(f'Input : {input_str}\nOutput: {output_str}')
# => Input : 'Genova, Italy' 'today'
# => Output: in Genova, Italy, today is sunny! Temperature is 20 degrees Celsius.

Afterward, how the tool instance must be used in a chain/agent?

having a tool that wraps any custom python function could be an example of general common interest for langchain community.
That's also related to the application problem: How a LLM-based application, integrates a custom function (API)? that could be implemented as a chain/agent, right?

Thanks a lot
giorgio

[solyarisoftware]

BTW, related: #832