Building an AI Financial Analyst with the Assistants API

With OpenAI's release of the Assistants API, the race towards building autonomous AI agents has become significantly more user-friendly and reliable.

By combining tools like Retrieval, Code Interpreter, and function calling we have all the tools we need to accomplish increasingly complex tasks for users with a single prompt.

In case you're unfamiliar with the Assistants API:

An Assistant has instructions and can leverage models, tools, and knowledge to respond to user queries. The Assistants API currently supports three types of tools: Code Interpreter, Retrieval, and Function calling. 

In this guide, we'll look at how to build a financial analyst assistant using parallel function calling and the Assistants API. After setting that up, we'll also extend it to use Code Interpreter in order to visualize the data from our API calls.

In case you're unfamiliar with function calling:

Function calling allows you to describe functions to the Assistants and have it intelligently return the functions that need to be called along with their arguments.

For this example, we'll use the Financial Modeling Prep API and retrieve real-time financial data for the following endpoints:

• Key metrics
• Financial ratios
• Financial growth
• Financial statements (i.e. income statements, balance sheet, & cash flow statement)

By making each of these API calls available to our financial assistant, it will be able to retrieve data based on the user's question, analyze the results, and respond accordingly.

Also, since we now have parallel function calling, we can analyze multiple stocks for specific data with a single input. For example, you could ask questions like:

Compare the financial health of Microsoft and Apple over the last four years, focusing on their balance sheets and key financial ratios

Evaluate Amazon's financial growth trajectory over the past five quarters. Highlight key metrics and cash flow trends that indicate its growth pattern.

Overview of the Assistants API

Before we get into the code, let's briefly review the steps of creating an Assistant.

The Assistants API enables us to build specialized AI agents with distinct capabilities.

By combining Assistants with function calling, these agents can translate natural language into API calls, process the data from these API calls, and provide analyses based on the response.

Steps to Create a Financial Analyst Assistant

At a high-level, the steps we need to take to create an Assistant are:

1. Defining financial functions: We need to define the Financial Modeling Prep API calls to retrieve financial
2. Defining the Assistant: Our AI agent will use models and instructions alongside the function calling tool to retrieve & analyze financial data.
3. Creating a Thread: A thread is essentially a conversation flow where we can feed the agent with user queries, function call responses, and assistant replies.
4. Adding Messages: We then input user queries to the Thread in the form of Messages.
5. Running the Assistant: We then create a Run, which is the Assistant processing the Thread, calling necessary tools, and generating appropriate responses.

To get started, we'll build this in Colab notebook so we'll need to set up our environment by adding our OpenAI API key & Financial Modeling Prep API key into the Secrets manager.

Step 0: Setting up the Environment

We'll can setup our environment by importing necessary libraries and setting our API keys as follows:

import os
import json
import requests
from openai import OpenAI
import time

# API keys are stored in Google Colab's Secret Manager
OPENAI_API_KEY = userdata.get('OPENAI_API_KEY')
FMP_API_KEY = userdata.get('FMP_API_KEY')

os.environ["OPENAI_API_KEY"] = OPENAI_API_KEY
os.environ["FMP_API_KEY"] = FMP_API_KEY

client = OpenAI()

Step 1: Defining Financial Functions

Next, we need to define our API calls to FMP in order to retrieve financial data. For this example, we'll use the following endpoints:

• Financial statements (income, balance sheet, & cash flow)
• Financial ratios
• Key metrics
• Financial growth

Of course, to create an end-to-end financial analyst we'd want to extend this function calling capability to much more financial data, but this will get us started for basic analysis.

Below, you can see how we get_income_statement fetches and returns the income statement data in JSON format for a specified company (ticker), over a quarterly or annual period (period), and a set (limit) of periods to analyze:

# Define financial statement functions
def get_income_statement(ticker, period, limit):
    url = f"https://financialmodelingprep.com/api/v3/income-statement/{ticker}?period={period}&limit={limit}&apikey={FMP_API_KEY}"
    response = requests.get(url)
    return json.dumps(response.json())

def get_balance_sheet(ticker, period, limit):
    # Code to fetch and return cash flow statement

def get_cash_flow_statement(ticker, period, limit):
    # Code to fetch and return cash flow statement

def get_key_metrics(ticker, period, limit):
    # Code to fetch and return cash flow statement

def get_financial_ratios(ticker, period, limit):
    # Code to fetch and return cash flow statement

def get_financial_growth(ticker, period, limit):
    # Code to fetch and return cash flow statement

Step 2: Map available functions

Next, we'll create a dictionary mapping function names to their corresponding function definitions with available_functions to facilitate the integration of our API endpoints into the Assistant's workflow.

# Map available functions
available_functions = {
    "get_income_statement": get_income_statement,
    "get_balance_sheet": get_balance_sheet,
    "get_cash_flow_statement": get_cash_flow_statement,
    "get_key_metrics": get_key_metrics,
    "get_financial_ratios": get_cash_flow_statement,
    "get_financial_growth": get_financial_ratios
}

Step 3: Creating the Assistant

Next, we'll create a main function called run_assistant that takes in the user_messsage. This user message will map the input to the ticker, period, and limit.

Next, we create our Assistant with the following parameters:

• Instructions: This controls the overall behavior of the assistant i.e. Act as a financial analyst by accessing financial data through the Financial Modeling Prep API. Your capabilities include analyzing key metrics, comprehensive financial statements, vital financial ratios, and tracking financial growth trends, etc, etc.
• Model: We'll use GPT-4 Turbo gpt-4-1106-preview
• Tools: Here we provide the functions the assistant has access to i.e. get_income_statement, etc.

# Define the main function
def run_assistant(user_message):

  # Creating an assistant with specific instructions and tools
  assistant = client.beta.assistants.create(
      instructions="Act as a financial analyst by accessing detailed financial data through the Financial Modeling Prep API. Your capabilities include analyzing key metrics, comprehensive financial statements, vital financial ratios, and tracking financial growth trends. ",
      model="gpt-4-1106-preview",
  tools=[
            {"type": "function", "function": {"name": "get_income_statement", "parameters": {"type": "object", "properties": {"ticker": {"type": "string"}, "period": {"type": "string"}, "limit": {"type": "integer"}}}}},
            # same for the rest of the financial functions
          ])

Step 4: Initiating a Thread

Next, we need to create a Thread, which as OpenAI describes is:

A conversation session between an Assistant and a user. Threads store Messages and automatically handle truncation to fit content into a model’s context.

  # Creating a new thread
  thread = client.beta.threads.create()

Step 5: Adding Messages to the Thread

Next, we can add a user Message to the thread.

Note that since we're using function calling, it will automatically map the user message to the required parameters for the API call, meaning we can retrieve ticker, period, year from natural language inputs...quite powerful.

  # Adding a user message to the thread
  client.beta.threads.messages.create(
      thread_id=thread.id,
      role="user",
      content=user_message
  )

Step 6: Running and Monitoring the Assistant

Now that we have our Assistant, Thread, and Message, let's create a Run, which initiates the Assistant's processing of the user's request on the Thread.

6.1 Start a Run

  # Running the assistant on the created thread
  run = client.beta.threads.runs.create(thread_id=thread.id, assistant_id=assistant.id)

6.2 Monitor and Manage the Run:

Next we want to loop continuously checks the status of the Run until it's completed.

• Retrieve Run Status: Regularly checks the current status of the Run.
  • run = client.beta.threads.runs.retrieve(thread_id=thread.id, run_id=run.id)
• Retrieve Run Steps: Fetches the steps the Run has taken, providing insight into the actions performed by the Assistant (mainly for monitoring and debugging purposes)
  • run_steps = client.beta.threads.runs.steps.list(thread_id=thread.id, run_id=run.id)
• Handle in_progress and queued Statuses: If the Run is still in progress or queued, wait for a short period before checking the status again.
  • Introduces a delay (time.sleep(5)) to avoid overwhelming the API with requests.
• Handle requires_action Status: If the Run requires action, typically when function calls are involved.
  • Extract tool calls from the Run and loop through them. Each tool call represents a function that the Assistant has decided to invoke based on the user's request.
• Execute each function using the arguments provided by the Assistant and gather the outputs.
• Submit the outputs back to the Run so the Assistant can continue processing.
  • client.beta.threads.runs.submit_tool_outputs(...)
• Handle completed Status: When the Run completes, fetch and print the messages (responses) generated by the Assistant.
  • Loop through messages and display their content based on the role (User or Assistant). Exit the loop after processing all the messages.

# Loop until the run completes or requires action
    while True:
        run = client.beta.threads.runs.retrieve(thread_id=thread.id, run_id=run.id)

        # Add run steps retrieval here
        run_steps = client.beta.threads.runs.steps.list(thread_id=thread.id, run_id=run.id)
        print("Run Steps:", run_steps)

        if run.status == "requires_action":
            tool_calls = run.required_action.submit_tool_outputs.tool_calls
            tool_outputs = []

            for tool_call in tool_calls:
                function_name = tool_call.function.name
                function_args = json.loads(tool_call.function.arguments)

                if function_name in available_functions:
                    function_to_call = available_functions[function_name]
                    output = function_to_call(**function_args)
                    tool_outputs.append({
                        "tool_call_id": tool_call.id,
                        "output": output,
                    })

            # Submit tool outputs and update the run
            client.beta.threads.runs.submit_tool_outputs(
                thread_id=thread.id,
                run_id=run.id,
                tool_outputs=tool_outputs
            )

        elif run.status == "completed":
            # List the messages to get the response
            messages = client.beta.threads.messages.list(thread_id=thread.id)
            for message in messages.data:
                role_label = "User" if message.role == "user" else "Assistant"
                message_content = message.content[0].text.value
                print(f"{role_label}: {message_content}\n")
            break  # Exit the loop after processing the completed run

        elif run.status == "failed":
            print("Run failed.")
            break

        elif run.status in ["in_progress", "queued"]:
            print(f"Run is {run.status}. Waiting...")
            time.sleep(5)  # Wait for 5 seconds before checking again

        else:
            print(f"Unexpected status: {run.status}")
            break

Step 7: Analyzing the Output

Finally, let's go and execute the run_assistant function with the following user message:

Can you compare the financial health of Microsoft and Apple over the last four years, focusing on their balance sheets and key financial ratios?

Which gives the following result...

Step 8: Enabling Code Interpreter

Alright, now that our financial assistant is working with function calling, let's take it a step further and enable the Code Interpreter tool:

Code Interpreter allows the Assistants API to write and run Python code in a sandboxed execution environment. This tool can process files with diverse data and formatting, and generate files with data and images of graphs. 

To do this, all we need to add the tool to our Assistant:

        # previous assistant code
        model="gpt-4-1106-preview",
        tools=[
          {"type": "code_interpreter"},
          {"type": "function", "function": {"name": "get_income_statement"...}

Next, all we need to do is handle the file outputs when the status is complete and save them in our notebook:

    elif run.status == "completed":
      # same code as before
  
                # Check the type of message content and handle accordingly
                for content in message.content:
                    if content.type == "text":
                        message_content = content.text.value
                        print(f"{role_label}: {message_content}\n")
                    elif content.type == "image_file":
                        # Handle image file content, e.g., print the file ID or download the image
                        image_file_id = content.image_file.file_id
                         # Define a path to save the image
                        image_save_path = f"./image_{image_file_id}.png"
                        # Download and save the image
                        download_and_save_image(image_file_id, image_save_path)

Now, if I ask a question like...

Evaluate Microsoft vs. Googles's revenue & profitability} growth over the past 4 quarters. Visualize the results with one or more charts.

This gives us...

Nice.

Of course there's much more we can do to improve these results, either with some prompt engineering or fine tuning, but we'll save that for later.

Summary: Building an AI Financial Research Assistant

As we discussed, the Assistants API is likely going to lead the current AI agent revolution as it makes developing these agentic experiences significantly more accessible and reliable for both developers and users.

We'll continue building out more advanced examples of Assistants over the coming weeks, but for now here's a brief summary:

• 🚀 Assistants API: OpenAI's Assistants API offers tools like Retrieval, Code Interpreter, and function calling, making complex task handling more efficient.
• 🤖 Assistant Capabilities: Assistants can use models, tools, and knowledge to respond to queries, with the Assistants API supporting Code Interpreter, Retrieval, and Function calling.
• 📈 Financial Analyst Assistant: The guide demonstrates building a financial analyst assistant using parallel function calling and the Assistants API, incorporating Code Interpreter for data visualization.
• 🧑‍💻 Function Calling: Function calling enables Assistants to intelligently return necessary functions and arguments for specific tasks.
• 🔄 Assistant Creation Steps: To create a financial analyst assistant, steps involve defining financial functions, creating an Assistant with specific instructions, setting up a conversation thread, adding user queries, and processing responses..
• 📝 Output Analysis: The final step involves executing the run_assistant function with a specific user query and analyzing the assistant's financial data response.

Access the full code for this tutorial