Superior-Agents 🤖⛏️

AI-powered stock analysis agent with multi-agent system for comprehensive market research and financial analysis.

Table of Contents

• Features
• Architecture
• Tech Stack
• Installation
• Configuration
• Usage
• Project Structure
• Customization
• Troubleshooting
• Development

Features

• Multi-Agent Architecture: Three specialized agents work together to provide comprehensive stock analysis
• Real-time Market Data: Fetches live stock prices, performance metrics, and financial data
• Market Intelligence: Uses Perplexity API to gather the latest news, trends, and analyst opinions
• Automated Reports: Generates professional markdown reports from the analysis
• Web API: FastAPI interface for easy integration and access
• Interactive Web Interface: User-friendly dashboard for stock analysis
• Workflow Visualization: Mermaid graph visualization of the agent workflow
• Customizable Prompts: Configurable system prompts for different analysis needs

Architecture

Overview

The Superior-Agent system consists of three specialized agents coordinated by a supervisor using LangGraph's multi-agent orchestration:

• Web Search Expert: Gathers current market news, trends, and analyst opinions using Perplexity API
• Finance Analyst: Fetches stock prices, performance metrics, and financial data using yfinance
• Report Generator: Compiles all gathered data into professional markdown reports
• Supervisor: Orchestrates the workflow between agents to generate comprehensive analyses

Workflow

1. Financial Manager Agent (supervisor) receives the analysis query and coordinates the workflow
2. Web Search Agent uses Perplexity API to gather market news and trends
3. Yahoo Finance Agent fetches live stock prices, performance metrics, and financial data
4. Report Generator Agent compiles all gathered information into a professional report
5. Reports are saved as markdown files in the output/ directory

Tech Stack

• LangGraph - State management and multi-agent orchestration
• LangGraph Supervisor - Multi-agent supervisor functionality
• LangChain - LLM integration and tool management
• FastAPI - Web API framework
• yfinance - Financial data fetching
• Perplexity API - Market research and news gathering
• Pydantic - Data validation
• uvicorn - ASGI server
• Jinja2 - Template rendering
• IPython - Interactive Python functionality
• Streamlit - Optional web application framework

Installation

1. Clone the repository:

   git clone https://github.com/devgomesai/Superior-Agent.git
   cd superior-agent

2. Create a virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies:

   # Using pip
   pip install -e .
   
   # Or using uv (recommended)
   uv pip install -e .

Configuration

1. Create a .env file in the project root directory:

   # Perplexity API key for market research
   PERPLEXITY_API_KEY=your_perplexity_api_key_here
   
   # LLM provider and model selection
   # Examples: groq:mixtral-8x7b-32768, anthropic:claude-3-5-sonnet-20241022
   LLM_CHOICE=groq:mixtral-8x7b-32768
   
   # API keys for your selected LLM provider
   GROQ_API_KEY=gsk_your_groq_api_key_here
   ANTHROPIC_API_KEY=sk-ant-your_anthropic_api_key_here

   For more LLM options, refer to the LangChain documentation.

2. The application automatically uses these environment variables for:

   • Perplexity API authentication for market research
   • LLM model selection and credentials

Usage

API Mode (Recommended)

1. Start the API server:

   uvicorn src.agent.api.api:app --reload

   Or without auto-reload:

   uvicorn src.agent.api.api:app

2. Access the application:

   • Web interface: http://127.0.0.1:8000
   • API documentation: http://127.0.0.1:8000/docs

API Endpoints

• POST /analyze - Analyze stock using the agent workflow

  curl -X POST "http://127.0.0.1:8000/analyze" \
    -H "Content-Type: application/json" \
    -d '{"query": "Analyze Tesla stock (TSLA) performance and financial metrics"}'

• GET / - Home page with stock analysis interface

• GET /health - Health check endpoint

  curl -X GET "http://127.0.0.1:8000/health"

• GET /output-files - List all generated stock reports

  curl -X GET "http://127.0.0.1:8000/output-files"

• GET /output-files/{filename} - Get specific report content

  curl -X GET "http://127.0.0.1:8000/output-files/stock_report_AAPL_20251027_094248.md"

Interactive Command-Line Mode

Run the application directly for interactive analysis:

python -m src.tests.main

Or from the src directory:

cd src
python -m tests.main

Follow the prompts to enter your stock analysis query.

Web Interface Features

The interactive web interface (http://127.0.0.1:8000) includes:

• Stock query input form for analysis requests
• Real-time display of agent workflow and responses
• Download section for previously generated reports
• Refresh functionality to update report listings
• Syntax-highlighted JSON response viewer

Project Structure

superior-agent/
├── src/
│   ├── agent/
│   │   ├── api/
│   │   │   ├── __init__.py
│   │   │   └── api.py                    # FastAPI endpoints
│   │   ├── __init__.py
│   │   └── agent.py                      # Core agent workflow
│   ├── prompts/
│   │   └── agent_prompts.py              # Agent system prompts
│   ├── templates/
│   │   └── index.html                    # Web interface
│   ├── tests/
│   │   ├── main.py                       # Interactive CLI mode
│   │   ├── test.py                       # Test template
│   │   └── tests.py                      # Test utilities
│   ├── tools/
│   │   └── stock_analysis_tools.py       # Market data tools
│   ├── __init__.py
│   └── requirements.txt
├── output/                               # Generated stock reports
├── .gitignore
├── .python-version
├── agent_flow.json                       # Workflow configuration
├── architecture.png                      # Architecture diagram
├── Dockerfile
├── graph.png                             # Workflow visualization
├── pyproject.toml                        # Project configuration
├── README.md
├── trace.png                             # Debug trace
└── uv.lock

Customization

Prompts

Customize agent behavior in src/prompts/agent_prompts.py:

• WEB_SEARCH_AGENT_PROMPT - Web research agent configuration
• YAHOO_FINANCE_AGENT_PROMPT - Finance analyst configuration
• REPORT_GENERATOR_AGENT_PROMPT - Report generator configuration
• SUPERVISOR_PROMPT - Workflow coordinator configuration

Tools

Available tools in src/tools/stock_analysis_tools.py:

• web_search_news() - Search market news using Perplexity API
• get_stock_price() - Fetch current stock price and information
• get_stock_performance() - Retrieve historical performance data
• get_financial_metrics() - Get key financial metrics
• save_report_to_file() - Save analysis reports to markdown

Configuration Files

• pyproject.toml - Project metadata and dependencies
• agent_flow.json - Agent workflow configuration
• graph.png - Auto-generated workflow visualization

Troubleshooting

Issue	Solution
API Keys Invalid	Verify your Perplexity and LLM API keys have sufficient credits
No Internet Connection	The system requires internet for fetching financial data and research
LLM Access Error	Ensure your LLM API key is properly configured in .env
Rate Limits Exceeded	Be aware of API rate limits for Perplexity and Yahoo Finance
Port 8000 Already in Use	Specify a different port: uvicorn src.agent.api.api:app --port 8001

Development

Setup

Install the package in editable mode for development:

pip install -e .

Running Tests

Test scripts are located in src/tests/:

• main.py - Interactive command-line interface for testing
• test.py - Test template (commented)
• tests.py - Additional test utilities

Run interactive analysis to test functionality:

python -m src.tests.main

Workflow Visualization

The application automatically generates workflow visualizations (graph.png) when run, useful for debugging the agent flow.

Acknowledgments

• LangChain and LangGraph for the multi-agent framework
• yfinance for financial data access
• Perplexity for market research capabilities
• FastAPI for the web framework
• Jinja2 for template rendering