docs/guides/financial_data_api.md

# Analyzing Financial Data with AI Agents using Swarms Framework

In the rapidly evolving landscape of quantitative finance, the integration of artificial intelligence with financial data analysis has become increasingly crucial. This blog post will explore how to leverage the power of AI agents, specifically using the Swarms framework, to analyze financial data from various top-tier data providers. We'll demonstrate how to connect these agents with different financial APIs, enabling sophisticated analysis and decision-making processes.

## Table of Contents

1. [Introduction to Swarms Framework](#introduction-to-swarms-framework)
2. [Setting Up the Environment](#setting-up-the-environment)
3. [Connecting AI Agents with Financial Data Providers](#connecting-ai-agents-with-financial-data-providers)
   - [Polygon.io](#polygonio)
   - [Alpha Vantage](#alpha-vantage)
   - [Yahoo Finance](#yahoo-finance)
   - [IEX Cloud](#iex-cloud)
   - [Finnhub](#finnhub)
4. [Advanced Analysis Techniques](#advanced-analysis-techniques)
5. [Best Practices and Considerations](#best-practices-and-considerations)
6. [Conclusion](#conclusion)

## Introduction to Swarms Framework

The Swarms framework is a powerful tool for building and deploying AI agents that can interact with various data sources and perform complex analyses. In the context of financial data analysis, Swarms can be used to create intelligent agents that can process large volumes of financial data, identify patterns, and make data-driven decisions. Explore our github for examples, applications, and more.

## Setting Up the Environment

Before we dive into connecting AI agents with financial data providers, let's set up our environment:

1. Install the Swarms framework:

```bash
pip install -U swarms
```

2. Install additional required libraries:

```bash
pip install requests pandas numpy matplotlib
```

3. Set up your API keys for the various financial data providers. It's recommended to use environment variables or a secure configuration file to store these keys.

## Connecting AI Agents with Financial Data Providers

Now, let's explore how to connect AI agents using the Swarms framework with different financial data providers.

### Polygon.io

First, we'll create an AI agent that can fetch and analyze stock data from Polygon.io.

```python
import os
from swarms import Agent
from swarms.models import OpenAIChat
from dotenv import load_dotenv
import requests
import pandas as pd

load_dotenv()

# Polygon.io API setup
POLYGON_API_KEY = os.getenv("POLYGON_API_KEY")
POLYGON_BASE_URL = "https://api.polygon.io/v2"

# OpenAI API setup
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

# Create an instance of the OpenAIChat class
model = OpenAIChat(
    openai_api_key=OPENAI_API_KEY,
    model_name="gpt-4",
    temperature=0.1
)

# Initialize the agent
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    system_prompt="You are a financial analysis AI assistant. Your task is to analyze stock data and provide insights.",
    llm=model,
    max_loops=1,
    dashboard=False,
    verbose=True
)

def get_stock_data(symbol, from_date, to_date):
    endpoint = f"{POLYGON_BASE_URL}/aggs/ticker/{symbol}/range/1/day/{from_date}/{to_date}"
    params = {
        'apiKey': POLYGON_API_KEY,
        'adjusted': 'true'
    }
    response = requests.get(endpoint, params=params)
    data = response.json()
    return pd.DataFrame(data['results'])

# Example usage
symbol = "AAPL"
from_date = "2023-01-01"
to_date = "2023-12-31"

stock_data = get_stock_data(symbol, from_date, to_date)

analysis_request = f"""
Analyze the following stock data for {symbol} from {from_date} to {to_date}:

{stock_data.to_string()}

Provide insights on the stock's performance, including trends, volatility, and any notable events.
"""

analysis = agent.run(analysis_request)
print(analysis)
```

In this example, we've created an AI agent that can fetch stock data from Polygon.io and perform an analysis based on that data. The agent uses the GPT-4 model to generate insights about the stock's performance.

### Alpha Vantage

Next, let's create an agent that can work with Alpha Vantage data to perform fundamental analysis.

```python
import os
from swarms import Agent
from swarms.models import OpenAIChat
from dotenv import load_dotenv
import requests

load_dotenv()

# Alpha Vantage API setup
ALPHA_VANTAGE_API_KEY = os.getenv("ALPHA_VANTAGE_API_KEY")
ALPHA_VANTAGE_BASE_URL = "https://www.alphavantage.co/query"

# OpenAI API setup
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

# Create an instance of the OpenAIChat class
model = OpenAIChat(
    openai_api_key=OPENAI_API_KEY,
    model_name="gpt-4",
    temperature=0.1
)

# Initialize the agent
agent = Agent(
    agent_name="Fundamental-Analysis-Agent",
    system_prompt="You are a financial analysis AI assistant specializing in fundamental analysis. Your task is to analyze company financials and provide insights.",
    llm=model,
    max_loops=1,
    dashboard=False,
    verbose=True
)

def get_income_statement(symbol):
    params = {
        'function': 'INCOME_STATEMENT',
        'symbol': symbol,
        'apikey': ALPHA_VANTAGE_API_KEY
    }
    response = requests.get(ALPHA_VANTAGE_BASE_URL, params=params)
    return response.json()

# Example usage
symbol = "MSFT"

income_statement = get_income_statement(symbol)

analysis_request = f"""
Analyze the following income statement data for {symbol}:

{income_statement}

Provide insights on the company's financial health, profitability trends, and any notable observations.
"""

analysis = agent.run(analysis_request)
print(analysis)
```

This example demonstrates an AI agent that can fetch income statement data from Alpha Vantage and perform a fundamental analysis of a company's financials.

### Yahoo Finance

Now, let's create an agent that can work with Yahoo Finance data to perform technical analysis.

```python
import os
from swarms import Agent
from swarms.models import OpenAIChat
from dotenv import load_dotenv
import yfinance as yf
import pandas as pd

load_dotenv()

# OpenAI API setup
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

# Create an instance of the OpenAIChat class
model = OpenAIChat(
    openai_api_key=OPENAI_API_KEY,
    model_name="gpt-4",
    temperature=0.1
)

# Initialize the agent
agent = Agent(
    agent_name="Technical-Analysis-Agent",
    system_prompt="You are a financial analysis AI assistant specializing in technical analysis. Your task is to analyze stock price data and provide insights on trends and potential trading signals.",
    llm=model,
    max_loops=1,
    dashboard=False,
    verbose=True
)

def get_stock_data(symbol, start_date, end_date):
    stock = yf.Ticker(symbol)
    data = stock.history(start=start_date, end=end_date)
    return data

# Example usage
symbol = "GOOGL"
start_date = "2023-01-01"
end_date = "2023-12-31"

stock_data = get_stock_data(symbol, start_date, end_date)

# Calculate some technical indicators
stock_data['SMA_20'] = stock_data['Close'].rolling(window=20).mean()
stock_data['SMA_50'] = stock_data['Close'].rolling(window=50).mean()

analysis_request = f"""
Analyze the following stock price data and technical indicators for {symbol} from {start_date} to {end_date}:

{stock_data.tail(30).to_string()}

Provide insights on the stock's price trends, potential support and resistance levels, and any notable trading signals based on the moving averages.
"""

analysis = agent.run(analysis_request)
print(analysis)
```

This example shows an AI agent that can fetch stock price data from Yahoo Finance, calculate some basic technical indicators, and perform a technical analysis.

### IEX Cloud

Let's create an agent that can work with IEX Cloud data to analyze company news sentiment.

```python
import os
from swarms import Agent
from swarms.models import OpenAIChat
from dotenv import load_dotenv
import requests

load_dotenv()

# IEX Cloud API setup
IEX_CLOUD_API_KEY = os.getenv("IEX_CLOUD_API_KEY")
IEX_CLOUD_BASE_URL = "https://cloud.iexapis.com/stable"

# OpenAI API setup
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

# Create an instance of the OpenAIChat class
model = OpenAIChat(
    openai_api_key=OPENAI_API_KEY,
    model_name="gpt-4",
    temperature=0.1
)

# Initialize the agent
agent = Agent(
    agent_name="News-Sentiment-Analysis-Agent",
    system_prompt="You are a financial analysis AI assistant specializing in news sentiment analysis. Your task is to analyze company news and provide insights on the overall sentiment and potential impact on the stock.",
    llm=model,
    max_loops=1,
    dashboard=False,
    verbose=True
)

def get_company_news(symbol, last_n):
    endpoint = f"{IEX_CLOUD_BASE_URL}/stock/{symbol}/news/last/{last_n}"
    params = {'token': IEX_CLOUD_API_KEY}
    response = requests.get(endpoint, params=params)
    return response.json()

# Example usage
symbol = "TSLA"
last_n = 10

news_data = get_company_news(symbol, last_n)

analysis_request = f"""
Analyze the following recent news articles for {symbol}:

{news_data}

Provide insights on the overall sentiment of the news, potential impact on the stock price, and any notable trends or events mentioned.
"""

analysis = agent.run(analysis_request)
print(analysis)
```

This example demonstrates an AI agent that can fetch recent news data from IEX Cloud and perform a sentiment analysis on the company news.

### Finnhub

Finally, let's create an agent that can work with Finnhub data to analyze earnings estimates and recommendations.

```python
import os
from swarms import Agent
from swarms.models import OpenAIChat
from dotenv import load_dotenv
import finnhub

load_dotenv()

# Finnhub API setup
FINNHUB_API_KEY = os.getenv("FINNHUB_API_KEY")
finnhub_client = finnhub.Client(api_key=FINNHUB_API_KEY)

# OpenAI API setup
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

# Create an instance of the OpenAIChat class
model = OpenAIChat(
    openai_api_key=OPENAI_API_KEY,
    model_name="gpt-4",
    temperature=0.1
)

# Initialize the agent
agent = Agent(
    agent_name="Earnings-Analysis-Agent",
    system_prompt="You are a financial analysis AI assistant specializing in earnings analysis. Your task is to analyze earnings estimates and recommendations to provide insights on a company's financial outlook.",
    llm=model,
    max_loops=1,
    dashboard=False,
    verbose=True
)

def get_earnings_estimates(symbol):
    return finnhub_client.earnings_calendar(symbol=symbol, from_date="2023-01-01", to_date="2023-12-31")

def get_recommendations(symbol):
    return finnhub_client.recommendation_trends(symbol)

# Example usage
symbol = "NVDA"

earnings_estimates = get_earnings_estimates(symbol)
recommendations = get_recommendations(symbol)

analysis_request = f"""
Analyze the following earnings estimates and recommendations for {symbol}:

Earnings Estimates:
{earnings_estimates}

Recommendations:
{recommendations}

Provide insights on the company's expected financial performance, analyst sentiment, and any notable trends in the recommendations.
"""

analysis = agent.run(analysis_request)
print(analysis)
```

This example shows an AI agent that can fetch earnings estimates and analyst recommendations from Finnhub and perform an analysis on the company's financial outlook.

## Advanced Analysis Techniques

To further enhance the capabilities of our AI agents, we can implement more advanced analysis techniques:

1. Multi-source analysis: Combine data from multiple providers to get a more comprehensive view of a stock or market.

2. Time series forecasting: Implement machine learning models for price prediction.

3. Sentiment analysis of social media: Incorporate data from social media platforms to gauge market sentiment.

4. Portfolio optimization: Use AI agents to suggest optimal portfolio allocations based on risk tolerance and investment goals.

5. Anomaly detection: Implement algorithms to detect unusual patterns or events in financial data.

Here's an example of how we might implement a multi-source analysis:

```python
import os
from swarms import Agent
from swarms.models import OpenAIChat
from dotenv import load_dotenv
import yfinance as yf
import requests
import pandas as pd

load_dotenv()

# API setup
POLYGON_API_KEY = os.getenv("POLYGON_API_KEY")
ALPHA_VANTAGE_API_KEY = os.getenv("ALPHA_VANTAGE_API_KEY")
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

# Create an instance of the OpenAIChat class
model = OpenAIChat(
    openai_api_key=OPENAI_API_KEY,
    model_name="gpt-4",
    temperature=0.1
)

# Initialize the agent
agent = Agent(
    agent_name="Multi-Source-Analysis-Agent",
    system_prompt="You are a financial analysis AI assistant capable of analyzing data from multiple sources. Your task is to provide comprehensive insights on a stock based on various data points.",
    llm=model,
    max_loops=1,
    dashboard=False,
    verbose=True
)

def get_stock_data_yf(symbol, start_date, end_date):
    stock = yf.Ticker(symbol)
    return stock.history(start=start_date, end=end_date)

def get_stock_data_polygon(symbol, from_date, to_date):
    endpoint = f"https://api.polygon.io/v2/aggs/ticker/{symbol}/range/1/day/{from_date}/{to_date}"
    params = {'apiKey': POLYGON_API_KEY, 'adjusted': 'true'}
    response = requests.get(endpoint, params=params)
    data = response.json()
    return pd.DataFrame(data['results'])

def get_company_overview_av(symbol):
    params = {
        'function': 'OVERVIEW',
        'symbol': symbol,
        'apikey': ALPHA_VANTAGE_API_KEY
    }
    response = requests.get("https://www.alphavantage.co/query", params=params)
    return response.json()

# Example usage
symbol = "AAPL"
start_date = "2023-01-01"
end_date = "2023-12-31"

yf_data = get_stock_data_yf(symbol, start_date, end_date)
polygon_data = get_stock_data_polygon(symbol, start_date, end_date)
av_overview = get_company_overview_av(symbol)

analysis_request = f"""
Analyze the following data for {symbol} from {start_date} to {end_date}:

Yahoo Finance Data:
{yf_data.tail().to_string()}

Polygon.io Data:
{polygon_data.tail().to_string()}

Alpha Vantage Company Overview:
{av_overview}

Provide a comprehensive analysis of the stock, including:
1. Price trends and volatility
2. Trading volume analysis
3. Fundamental analysis based on the company overview
4. Any discrepancies between data sources and potential reasons
5. Overall outlook and potential risks/opportunities
"""

analysis = agent.run(analysis_request)
print(analysis)
```

This multi-source analysis example combines data from Yahoo Finance, Polygon.io, and Alpha Vantage to provide a more comprehensive view of a stock. The AI agent can then analyze this diverse set of data to provide deeper insights.

Now, let's explore some additional advanced analysis techniques:

### Time Series Forecasting

We can implement a simple time series forecasting model using the Prophet library and integrate it with our AI agent:

```python
import os
from swarms import Agent
from swarms.models import OpenAIChat
from dotenv import load_dotenv
import yfinance as yf
import pandas as pd
from prophet import Prophet
import matplotlib.pyplot as plt

load_dotenv()

OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

model = OpenAIChat(
    openai_api_key=OPENAI_API_KEY,
    model_name="gpt-4",
    temperature=0.1
)

agent = Agent(
    agent_name="Time-Series-Forecast-Agent",
    system_prompt="You are a financial analysis AI assistant specializing in time series forecasting. Your task is to analyze stock price predictions and provide insights.",
    llm=model,
    max_loops=1,
    dashboard=False,
    verbose=True
)

def get_stock_data(symbol, start_date, end_date):
    stock = yf.Ticker(symbol)
    data = stock.history(start=start_date, end=end_date)
    return data

def forecast_stock_price(data, periods=30):
    df = data.reset_index()[['Date', 'Close']]
    df.columns = ['ds', 'y']
    
    model = Prophet()
    model.fit(df)
    
    future = model.make_future_dataframe(periods=periods)
    forecast = model.predict(future)
    
    fig = model.plot(forecast)
    plt.savefig('forecast_plot.png')
    plt.close()
    
    return forecast

# Example usage
symbol = "MSFT"
start_date = "2020-01-01"
end_date = "2023-12-31"

stock_data = get_stock_data(symbol, start_date, end_date)
forecast = forecast_stock_price(stock_data)

analysis_request = f"""
Analyze the following time series forecast for {symbol}:

Forecast Data:
{forecast.tail(30).to_string()}

The forecast plot has been saved as 'forecast_plot.png'.

Provide insights on:
1. The predicted trend for the stock price
2. Any seasonal patterns observed
3. Potential factors that might influence the forecast
4. Limitations of this forecasting method
5. Recommendations for investors based on this forecast
"""

analysis = agent.run(analysis_request)
print(analysis)
```

This example demonstrates how to integrate a time series forecasting model (Prophet) with our AI agent. The agent can then provide insights based on the forecasted data.

### Sentiment Analysis of Social Media

We can use a pre-trained sentiment analysis model to analyze tweets about a company and integrate this with our AI agent:

```python
import os
from swarms import Agent
from swarms.models import OpenAIChat
from dotenv import load_dotenv
import tweepy
from textblob import TextBlob
import pandas as pd

load_dotenv()

# Twitter API setup
TWITTER_API_KEY = os.getenv("TWITTER_API_KEY")
TWITTER_API_SECRET = os.getenv("TWITTER_API_SECRET")
TWITTER_ACCESS_TOKEN = os.getenv("TWITTER_ACCESS_TOKEN")
TWITTER_ACCESS_TOKEN_SECRET = os.getenv("TWITTER_ACCESS_TOKEN_SECRET")

auth = tweepy.OAuthHandler(TWITTER_API_KEY, TWITTER_API_SECRET)
auth.set_access_token(TWITTER_ACCESS_TOKEN, TWITTER_ACCESS_TOKEN_SECRET)
api = tweepy.API(auth)

# OpenAI setup
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

model = OpenAIChat(
    openai_api_key=OPENAI_API_KEY,
    model_name="gpt-4",
    temperature=0.1
)

agent = Agent(
    agent_name="Social-Media-Sentiment-Agent",
    system_prompt="You are a financial analysis AI assistant specializing in social media sentiment analysis. Your task is to analyze sentiment data from tweets and provide insights on market perception.",
    llm=model,
    max_loops=1,
    dashboard=False,
    verbose=True
)

def get_tweets(query, count=100):
    tweets = api.search_tweets(q=query, count=count, tweet_mode="extended")
    return [tweet.full_text for tweet in tweets]

def analyze_sentiment(tweets):
    sentiments = [TextBlob(tweet).sentiment.polarity for tweet in tweets]
    return pd.DataFrame({'tweet': tweets, 'sentiment': sentiments})

# Example usage
symbol = "TSLA"
query = f"${symbol} stock"

tweets = get_tweets(query)
sentiment_data = analyze_sentiment(tweets)

analysis_request = f"""
Analyze the following sentiment data for tweets about {symbol} stock:

Sentiment Summary:
Positive tweets: {sum(sentiment_data['sentiment'] > 0)}
Negative tweets: {sum(sentiment_data['sentiment'] < 0)}
Neutral tweets: {sum(sentiment_data['sentiment'] == 0)}

Average sentiment: {sentiment_data['sentiment'].mean()}

Sample tweets and their sentiments:
{sentiment_data.head(10).to_string()}

Provide insights on:
1. The overall sentiment towards the stock
2. Any notable trends or patterns in the sentiment
3. Potential reasons for the observed sentiment
4. How this sentiment might impact the stock price
5. Limitations of this sentiment analysis method
"""

analysis = agent.run(analysis_request)
print(analysis)
```

This example shows how to perform sentiment analysis on tweets about a stock and integrate the results with our AI agent for further analysis.

### Portfolio Optimization

We can use the PyPortfolioOpt library to perform portfolio optimization and have our AI agent provide insights:

```python
import os
from swarms import Agent
from swarms.models import OpenAIChat
from dotenv import load_dotenv
import yfinance as yf
import pandas as pd
import numpy as np
from pypfopt import EfficientFrontier
from pypfopt import risk_models
from pypfopt import expected_returns

load_dotenv()

OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

model = OpenAIChat(
    openai_api_key=OPENAI_API_KEY,
    model_name="gpt-4",
    temperature=0.1
)

agent = Agent(
    agent_name="Portfolio-Optimization-Agent",
    system_prompt="You are a financial analysis AI assistant specializing in portfolio optimization. Your task is to analyze optimized portfolio allocations and provide investment advice.",
    llm=model,
    max_loops=1,
    dashboard=False,
    verbose=True
)

def get_stock_data(symbols, start_date, end_date):
    data = yf.download(symbols, start=start_date, end=end_date)['Adj Close']
    return data

def optimize_portfolio(data):
    mu = expected_returns.mean_historical_return(data)
    S = risk_models.sample_cov(data)
    
    ef = EfficientFrontier(mu, S)
    weights = ef.max_sharpe()
    cleaned_weights = ef.clean_weights()
    
    return cleaned_weights

# Example usage
symbols = ["AAPL", "GOOGL", "MSFT", "AMZN", "FB"]
start_date = "2018-01-01"
end_date = "2023-12-31"

stock_data = get_stock_data(symbols, start_date, end_date)
optimized_weights = optimize_portfolio(stock_data)

analysis_request = f"""
Analyze the following optimized portfolio allocation:

{pd.Series(optimized_weights).to_string()}

The optimization aimed to maximize the Sharpe ratio based on historical data from {start_date} to {end_date}.

Provide insights on:
1. The recommended allocation and its potential benefits
2. Any notable concentrations or diversification in the portfolio
3. Potential risks associated with this allocation
4. How this portfolio might perform in different market conditions
5. Recommendations for an investor considering this allocation
6. Limitations of this optimization method
"""

analysis = agent.run(analysis_request)
print(analysis)
```

This example demonstrates how to perform portfolio optimization using the PyPortfolioOpt library and have our AI agent provide insights on the optimized allocation.

## Best Practices and Considerations

When using AI agents for financial data analysis, consider the following best practices:

1. Data quality: Ensure that the data you're feeding into the agents is accurate and up-to-date.

2. Model limitations: Be aware of the limitations of both the financial models and the AI models being used.

3. Regulatory compliance: Ensure that your use of AI in financial analysis complies with relevant regulations.

4. Ethical considerations: Be mindful of potential biases in AI models and strive for fair and ethical analysis.

5. Continuous monitoring: Regularly evaluate the performance of your AI agents and update them as needed.

6. Human oversight: While AI agents can provide valuable insights, human judgment should always play a role in financial decision-making.

7. Privacy and security: Implement robust security measures to protect sensitive financial data.

## Conclusion

The integration of AI agents with financial data APIs opens up exciting possibilities for advanced financial analysis. By leveraging the power of the Swarms framework and connecting it with various financial data providers, analysts and quants can gain deeper insights, automate complex analyses, and potentially make more informed investment decisions.

However, it's crucial to remember that while AI agents can process vast amounts of data and identify patterns that humans might miss, they should be used as tools to augment human decision-making rather than replace it entirely. The financial markets are complex systems influenced by numerous factors, many of which may not be captured in historical data or current models.

As the field of AI in finance continues to evolve, we can expect even more sophisticated analysis techniques and integrations. Staying updated with the latest developments in both AI and financial analysis will be key to leveraging these powerful tools effectively.