Overview

Analyst Team

• Fundamentals Analyst：
  • evaluates company financial reports
• Sentiment Analyst:
  • Analyzes social media, news using sentiment scoring algorithm
• Technical Analyst:
  • Uses technical indicators to predict price movements, including MACD, RSI, Bollinger Bands, etc.
• Special Analyst (bypass first):
  • Assess the insights of some special topics.

Researcher Team

• Bullish researcher：assess the insights provided by the Analyst Team, evaluate the buy in reasons
• Bearish researcher：assess the insights provided by the Analyst Team, evaluate the sell or hold reasons
• Debate: debate on both sides (bull/bear)

Trading Team

• Trading team: Assess the insights provided by the Analyst Team and Researcher Team, and make a final decision on whether to buy, sell, or hold the stock.
  • Give the signal BUY/SELL/HOLD to provided equity
  • Give the timing when the signal is BUY/SELL

Risk Management Team

• Evaluation of risk: includes risky risk analysis, neutral risk analysis, safe risk analysis
• Evaluation of risk: per analysis, evaluate the risk of the investment, including the potential loss and the probability of loss.
• Final decision: Based on the risk evaluation, make a final decision on whether approve or reject the trading decision.

Inputs/Outputs

Analyst Team

• Inputs
  • stockSymbol (ticker)
  • investmentPeriod (short+: within 2 week; short:within 1 month; medium: from 1 month to 6 months; long: from 6 months to 2 years)
• Outputs
  • insights provided by the Analyst Team

Researcher Team

• Inputs
  • investmentPeriod (short+: within 2 week; short:within 1 month; medium: from 1 month to 6 months; long: from 6 months to 2 years)
  • insights provided by the Analyst Team
• Outputs
  • debate result provided by the Researcher Team

Trading Team

• Inputs
  • debate result provided by the Researcher Team
• Outputs
  • trading signal: BUY/SELL/HOLD
  • trading timing: when to BUY/SELL
  • reason for trading

Risk Management Team

• Inputs
  • insights provided by the Analyst Team
  • debate result provided by the Researcher Team
  • trading signal by the Trading Team
  • trading timing by the Trading Team
• Outputs
  • risk evaluation: APPROVE/REJECT
  • reason for risk evaluation

Workflow

Analyst Team

• Fundamentals Analyst
  (1) Call yFinance API or alphavantage API to get stock fundamentals data
  alphavantage API: get_company_overview
  input: {stockSymbol}
  output: company information

yFinance API: yfinance.Ticker.get_income_stmt
input: {stockSymbol}, {freq} (freq: "quarterly")
output: the quarterly income statements

yFinance API: yfinance.Ticker.get_balance_sheet
input: {stockSymbol}, {freq} (freq: "quarterly")
output: the quarterly balance sheets

yFinance API: yfinance.Ticker.get_cashflow
input: {stockSymbol}, {freq} (freq: "quarterly")
output: the quarterly cash flow

(2) return the financial summary report based on fundamentals data
User prompt: "Please summarize the financial data of {stockSymbol} based on the outputs of below MRC tools:

• {outputOfOverview},
• {outputOfIncomeStatement},
• {outputOfBalanceSheet},
• {outputOfCashFlow},
  For outputOfOverview focus on:
• Name
• EBITDA
• PERatio
• PEGRatio
• BookValue
• DividendPerShare
• DividendYield
• EPS
• RevenuePerShareTTM
• ProfitMargin
• DilutedEPSTTM
• ReturnOnAssetsTTM
• ReturnOnEquityTTM
• RevenueTTM
• QuarterlyEarningsGrowthYOY
• QuarterlyRevenueGrowthYOY
• AnalystTargetPrice
• AnalystRatingStrongBuy
• AnalystRatingBuy
• AnalystRatingHold
• AnalystRatingSell
• AnalystRatingStrongSell
• DividendDate
• ExDividendDate
  System prompt: "You are a helpful AI assistant."

• Sentiment Analyst
  (1) Call yFinance API to get news data
  yFinance API: yfinance.Ticker.news
  input: {stockSymbol}, {limit}
  limit: 20
  output: latest 20 news url link

(2) return the news sentiment analysis report based on news data
User prompt: "Please sentiment analysis based on the outputs of below MRC tools:

• {outputOfNewsSentiment}
  Focus on:
• title
• ticker_sentiment:
  • ticker
  • relevance_score
  • ticker_sentiment_score
  • ticker_sentiment_label
    Only consider the companies relates to {symbol} (e.g. Alphabet Inc relates to either GOOGL or GOOG)
    ."
    System prompt: "You are a news sentiment researcher tasked with analyzing news and trends."

(3) Call alphavantage API to get macro news data
alphavantage API: function=get_news_sentiment
topics："economy_fiscal,economy_monetary,economy_macro"
limit: 20
output: latest 20 news url link

• Technical Analyst
  (1) Call yFinance API to get technical indicators
  SMA
  input: {stockSymbol}, {time_period}
  time_period: 36
  output: SMA (simple moving average indicators)
  Prepare close_50_sm (time_period=50), close_200_sma (time_period=200)

EMA
input: {stockSymbol}, {time_period}
time_period: e.g. 30, 60
output: EMA (exponential moving average indicators)
Prepare close_10_ema (time_period=10)

MACD
data['MACD'] = data['EMA12'] - data['EMA26']
interval for yFinance API: "30m" when investmentPeriod=short+; "1d" when investmentPeriod=short; "1wk" when investmentPeriod=medium; "1mo" when investmentPeriod=long
valid intervals of period: [1m,2m,5m,15m,30m,60m,90m,1h,4h,1d,5d,1wk,1mo,3mo]
period for yFinance API: "3d" when investmentPeriod=short+; "30d" when investmentPeriod=short; "9mo" when investmentPeriod=medium; "3y" when investmentPeriod=long

MACD
data['Signal_Line'] = data['MACD'].ewm(span=9, adjust=False).mean()

RSI
input: {stockSymbol}
output: relative strength index indicators

BBANDS
input: {stockSymbol}
output: bollinger bands indicators

VWAP (Volume Weighted Average Price)
data['cum_price_volume'] = (data['Close'] * data['Volume']).cumsum()
data['cum_volume'] = data['Volume'].cumsum()
data['VWAP'] = data['cum_price_volume'] / data['cum_volume']

(2) return the technical analysis report based on technical indicators
User prompt: "Please return the technical analysis report based on the outputs of below MRC tools

• {outputOfSMA},
• {outputOfEMA},
• {outputOfMACD},
• {outputOfMACDSignal},
• {outputOfRSI},
• {outputOfBBANDS},
• {outputOfVWAP}
  ."
  System prompt: "You are a technical indicators researcher."

• Special Analyst
  (1) Call yFinance API to get closed price
  interval: 1d
  period: 5d

(2) Call yFinance API to get insider transactions (bypass first)
yFinance API: yfinance.Ticker.get_insider_transactions
input: {stockSymbol}
output: insider transactions of the stock ticker

Researcher Team

• Bullish researcher
  User prompt: "provide a bullish analysis for {stockSymbol}"
  Resources available:
  Company fundamentals report: {fundamentals_report}
  news sentiment report: {sentiment_report}
  Market research report: {technical_research_report}
  Report history of the debate: {memory}
  Use this information to deliver a compelling bull argument, refute the bear's concerns, and engage in a dynamic debate that demonstrates the strengths of the bull position. You must also address reflections and learn from lessons and mistakes you made in the past."

System prompt: "You are a Bull Analyst advocating for investing in the stock. Your task is to build a strong, evidence-based case emphasizing growth potential, competitive advantages, and positive market indicators. Leverage the provided research and data to address concerns and counter bearish arguments effectively.

Key points to focus on:

• Growth Potential: Highlight the company's market opportunities, revenue projections, and scalability.
• Competitive Advantages: Emphasize factors like unique products, strong branding, or dominant market positioning.
• Positive Indicators: Use financial health, industry trends, and recent positive news as evidence.
• Bear Counterpoints: Critically analyze the bear argument with specific data and sound reasoning, addressing concerns thoroughly and showing why the bull perspective holds stronger merit.
• Engagement: Present your argument in a conversational style, engaging directly with the bear analyst's points and debating effectively rather than just listing data."

• Bearish researcher
  User prompt: "provide a bearish analysis for {stockSymbol}"
  Resources available:
  Company fundamentals report: {fundamentals_report}
  news sentiment report: {sentiment_report}
  Market research report: {technical_research_report}
  Report history of the debate: {memory}
  Use this information to deliver a compelling bear argument, refute the bull's claims, and engage in a dynamic debate that demonstrates the risks and weaknesses of investing in the stock. You must also address reflections and learn from lessons and mistakes you made in the past."

System prompt: "You are a Bear Analyst making the case against investing in the stock. Your goal is to present a well-reasoned argument emphasizing risks, challenges, and negative indicators. Leverage the provided research and data to highlight potential downsides and counter bullish arguments effectively.

Key points to focus on:

• Risks and Challenges: Highlight factors like market saturation, financial instability, or macroeconomic threats that could hinder the stock's performance.
• Competitive Weaknesses: Emphasize vulnerabilities such as weaker market positioning, declining innovation, or threats from competitors.
• Negative Indicators: Use evidence from financial data, market trends, or recent adverse news to support your position.
• Bull Counterpoints: Critically analyze the bull argument with specific data and sound reasoning, exposing weaknesses or over-optimistic assumptions.
• Engagement: Present your argument in a conversational style, directly engaging with the bull analyst's points and debating effectively rather than simply listing facts.
  "

• Debate
  User prompt: "provide debate result based on both bullish analysis and bearish analysis"

Trading Team

User prompt: "provide trader_plan including:
- trading signal: BUY/SELL/HOLD
- trading timing: when/what price to BUY/SELL
- forecast period: "2 weeks" when investmentPeriod=short+; "1 month" when investmentPeriod=short; "1 year" when investmentPeriod=medium; "2 years" when investmentPeriod=long
- reason for trading"
System prompt: "You are a trading agent analyzing market data to make investment decisions. Based on your analysis, always include the following key information in your analysis:

1. PROPOSAL: BUY/HOLD/SELL' to confirm your recommendation.
2. TARGET PRICE: A 3-month mid-term forecast target price with currency based on analysis - Require: 1) provide a specific value; 2) the target price should be reasonable and its fluctuation does not exceed ±30% of the latest closing price - {close_price}.
3. CONFIDENCE: The degree of confidence in the decision (between 0 and 1)
4. RISK SCORE: Investment risk level (between 0 and 1, 0 is low risk and 1 is high risk)
5. LAST CLOSE PRICE: {close_price}
6. RATIONALE: A brief explanation of the reasoning behind the decision.

Target Price Calculation Guidelines:

• Based on valuation data from fundamental analysis
• Reference support and resistance levels from technical analysis
• Consider industry average valuations
• Incorporate market sentiment and news impact
• Even if market sentiment is overheated, target prices should be based on reasonable valuations.

Do not forget to utilize lessons from past decisions to learn from your mistakes. Here is some reflections from similar situations you traded in and the lessons learned: {past_memory_lession_learned}"

Risk Management Team

User prompt: "provide risk_plan including:
- risky risk analysis
- neutral risk analysis
- safe risk analysis
- final risk evaluation: APPROVE/REJECT
- reason for risk evaluation"
System prompt: "
As the Risk Management Judge and Debate Facilitator, your goal is to evaluate the debate between three risk analysts—Risky, Neutral, and Safe. Determine the best course of action for the trader. Choose Hold only if strongly justified by specific arguments, not as a fallback when all sides seem valid. Strive for clarity and decisiveness.

Guidelines for Decision-Making:

1. Summarize Key Arguments: Extract the strongest points from each analyst, focusing on relevance to the context.
2. Provide Rationale: Support your recommendation with direct quotes and counterarguments from the debate.
3. Refine the Trader's Plan: Start with the trader's original plan, {trader_plan}, and adjust it based on the analysts' insights.
4. Learn from Past Mistakes: Use lessons from {past_memory_lession_learned} to address prior misjudgments and improve the decision you are making now to make sure you don't make a wrong BUY/SELL/HOLD call that loses money.
   "

utils

Calculate close_price
call yFinance API to get close_price

lesson learner (bypss if vector DB server is not started)
(1) Store the final report in a vector database as memory with the analysis datetime
(2) compare the last report in memory with the actual closed market price based on the analysis datetime, to get the lesson learned
User prompt: "compare the last report in memory with the actual closed market price based on the analysis datetime, to get the lesson learned"
(3) Store the lesson learned in a vector database as past_memory_lession_learned with the analysis datetime

Layout Tips

(1) Use CLI to interact with the system

a. user input the stock symbol (e.g.GOOG), investment period (i.e.SHORT+/SHORT/MEDIUM/LONG)
b. system output to the console and the result file
- financial summary report
- news sentiment analysis report
- technical analysis report
- insider transactions
- bullish analysis
- bearish analysis
- debate result
- trading plan
- risk plan
Note: for each report to the console, limit the output to within 500 words

(2) Web UI

Layout

Top panel (bgcolor:white)

• Title: FinAgent (fgcolor:#050505;bold)

Main panel (bgcolor:white)

Input Session

• model: Input, input model. If model is provided, bypass MODEL_NAME in .env and the default model, if no input, then use MODEL_NAME in .env, if no MODEL_NAME in .env, then use the default model in the code.
• Symbol: Input, mandatory, input of stock symbol
• investment period: Select box, mandatory, input of investment period, value: SHORT+/SHORT/MEDIUM/LONG, default value: SHORT
• Submit: Button, click to verify mandatory elements first, if mandatory elements filled, then execute: finagent.py with paraeters: {symbol}, {investment period}
  Output Session
• Fundamentals Analysis: TagPanel, details of Fundamentals Analysis from the report after submitted.
• Sentiment Analysis: TagPanel, details of Sentiment Analysis from the report after submitted.
• Technical Analysis: TagPanel, details of Technical Analysis from the report after submitted.
• Research Analysis: TagPanel, details of Research Analysis from the report after submitted.
• Trading Analysis: TagPanel, details of Trading Analysis from the report after submitted.
• Risk Analysis: TagPanel, details of Risk Analysis from the report after submitted.
• Final Evaluation: TagPanel, final Risk Evaluation in Risk Analysis from the report after submitted.
• Report: textlink, link to the report (open a new window)

Style

• Single-page web
• red asterisk for mandatory fields

Libraries

• React
• Tailwind

Others

• folder: web
• web port: 3001
• user friendly in web and also fit to mobile OS like iOS screen

Appendix: Model

OpenRouter Model
API Key: OPENROUTER_API_KEY set in .env file
Model: set in .env file
Embedding Model: set in .env file
Note: openai embedding model(e.g. openai/text-embedding-3-small) may hit error "openai.BadRequestError: Error code: 400 - {'error': {'message': 'Model [object Object] does not support embeddings output modality', 'code': 400}}"

Appendix: API Information

alphavantage API
API Key: ALPHA_VANTAGE_API_KEY set in .env file
API documentation: https://www.alphavantage.co/documentation/#intelligence
Add sleep 1.2 seconds per request to prevent free API rate limiting
interval of Technical Analyst: "30min" when investmentPeriod=short+; "daily" when investmentPeriod=short; "weekly" when investmentPeriod=medium; "monthly" when investmentPeriod=long

yFinance API
API documentation: https://ranaroussi.github.io/yfinance/reference/index.html
period of Fundamentals Analyst: "30m" when investmentPeriod=short+; "1d" when investmentPeriod=short; "1wk" when investmentPeriod=medium; "1mo" when investmentPeriod=long

Appendix: storage

Vector database: Qdrant
Result file path: set in .env file. Default name: result_.log

Appendix: agents

Multiples agents:

• Fundamentals Analyst Agent
• Sentiment Analyst Agent
• Technical Analyst Agent
• Special Analyst Agent (bypass first)
• Bullish researcher Agent
• Bearish researcher Agent
• Debate Agent
• Trading Agent
• Risk Management Agent

Agent framework: LangGraph

Appendix: MRC

MRC Server: fastmcp

Appendix: folder structure under finAgent

src folder: python source code
src\agents folder: agents
src\tools folder: tools
src\utils folder: utility functions and helper modules
config folder: configuration files (e.g. .env file)
test folder: test code
.requirements.txt: pip install libraries
setup.cmd: create virtual environment by conda, and install requirement libraries
mcp-server-setup.cmd: install mcp server
vector-db-setup.cmd: install vector database
finagent.bat: run the code

Appendix: Library Selection

python==3.12.4
pandas==2.2.2
numpy==2.0.1
yfinance==1.0
alpha_vantage==3.0.0
qdrant-client==1.16.0
langgraph==1.0.0
langchain-core==1.0.0
langchain-openai==1.0.0
pydantic==2.11.7
python-dotenv==1.1.0
fastmcp==2.14.1
click==8.1.7
openai==2.12.0
fastapi==0.115.0
uvicorn[standard]==0.35.0
gunicorn==24.1.1

Appendix: testing

curl -X POST http://localhost:8000/analyze -H "Content-Type: application/json" -d '{"symbol": "AAPL", "period": "medium"}'