Quickstart
==========

This quickstart guide will walk you through creating a simple agent with Malevich Brain.

Basic Example
------------

In this example, we'll create a simple agent that can perform a calculation using a custom tool.

1. First, import the necessary modules:

.. code-block:: python

    from brain.agents.agent import Agent
    from brain.agents.llm.openai import OpenAIBaseLLM
    from brain.agents.tool import tool
    import asyncio
    import os

2. Create a simple calculation tool:

.. code-block:: python

    @tool(
        name="calculator",
        description="A tool that can perform basic calculations"
    )
    def calculator(operation: str, x: float, y: float) -> float:
        """
        Performs a basic arithmetic operation on two numbers.
        
        Args:
            operation: The operation to perform (add, subtract, multiply, divide)
            x: The first number
            y: The second number
            
        Returns:
            The result of the operation
        """
        match operation:
            case "add":
                return x + y
            case "subtract":
                return x - y
            case "multiply":
                return x * y
            case "divide":
                if y == 0:
                    raise ValueError("Cannot divide by zero")
                return x / y
            case _:
                raise ValueError(f"Unknown operation: {operation}")

3. Set up the OpenAI LLM:

.. code-block:: python

    # Get API key from environment variable
    api_key = os.environ.get("OPENAI_API_KEY")
    
    # Initialize the LLM
    llm = OpenAIBaseLLM(
        api_key=api_key,
        default_model="gpt-4o-mini"  # You can use other models as needed
    )

4. Create and run the agent:

.. code-block:: python

    async def main():
        # Create an agent with our calculator tool
        agent = Agent(
            llm=llm,
            tools=[calculator],
            instructions="You are an assistant that helps with calculations"
        )
        
        # Run the agent with a user prompt
        result = await agent.run("I need to multiply 123 by 456")
        print(result)
    
    # Run the async function
    if __name__ == "__main__":
        asyncio.run(main())

The agent will use the calculator tool to multiply the numbers and return the result.

Complete Example
---------------

Here's the complete example code:

.. code-block:: python

    from brain.agents.agent import Agent
    from brain.agents.llm.openai import OpenAIBaseLLM
    from brain.agents.tool import tool
    import asyncio
    import os
    
    @tool(
        name="calculator",
        description="A tool that can perform basic calculations"
    )
    def calculator(operation: str, x: float, y: float) -> float:
        """
        Performs a basic arithmetic operation on two numbers.
        
        Args:
            operation: The operation to perform (add, subtract, multiply, divide)
            x: The first number
            y: The second number
            
        Returns:
            The result of the operation
        """
        match operation:
            case "add":
                return x + y
            case "subtract":
                return x - y
            case "multiply":
                return x * y
            case "divide":
                if y == 0:
                    raise ValueError("Cannot divide by zero")
                return x / y
            case _:
                raise ValueError(f"Unknown operation: {operation}")
    
    async def main():
        # Get API key from environment variable
        api_key = os.environ.get("OPENAI_API_KEY")
        
        # Initialize the LLM
        llm = OpenAIBaseLLM(
            api_key=api_key,
            default_model="gpt-4o-mini"
        )
        
        # Create an agent with our calculator tool
        agent = Agent(
            llm=llm,
            tools=[calculator],
            instructions="You are an assistant that helps with calculations"
        )
        
        # Run the agent with a user prompt
        result = await agent.run("I need to multiply 123 by 456")
        print(result)
    
    if __name__ == "__main__":
        asyncio.run(main())