📊 Financial Research Agentic API

AI-Powered Financial Analysis API - A comprehensive platform combining a LangChain agent called Nexus with real-time market data to deliver professional stock analysis, market briefings, and comparative analytics.

🇧🇷 Versão em Português

🎯 Overview of Nexus Financial Agent

Nexus is an intelligent financial analysis streaming stateful agent that leverages Chain-of-Thought and Tools to provide:

Stock Analysis: Deep dive analysis of individual stocks with historical data, financials, and news
Market Pulse: Pre-market and intraday briefings with top movers and macro trends
Stock Showdown: Head-to-head comparative analysis of multiple tickers The system uses LangChain agents with specialized tools to fetch real-time data from yfinance and Tavily, providing data-driven insights with compliance-aware responses.

🏗️ Architecture

graph TB
    subgraph "Frontend Layer"
        UI[React UI<br/>TypeScript + Vite]
        Chat[C1Chat Component<br/>GenUI SDK]
    end
    
    subgraph "Backend Layer"
        API[FastAPI Server<br/>Port 8000]
        Agent[LangChain Agent<br/>OpenAI LLM]
        Memory[InMemory<br/>Checkpoint]
    end
    
    subgraph "Tools & Data Sources"
        YF[yfinance<br/>Stock Data]
        Tavily[Tavily API<br/>Web Search]
        Tools[Tools Layer]
    end
    
    UI --> Chat
    Chat -->|HTTP/SSE| API
    API --> Agent
    Agent --> Memory
    Agent --> Tools
    Tools --> YF
    Tools --> Tavily
    
    style UI fill:#61dafb
    style Agent fill:#00d084
    style Tools fill:#ff6b6b

🔄 Data Flow

sequenceDiagram
    participant User
    participant Frontend
    participant FastAPI
    participant Agent
    participant Tools
    participant External APIs
    
    User->>Frontend: Ask question about NVDA
    Frontend->>FastAPI: POST /api/chat
    FastAPI->>Agent: Process query with context
    
    loop Tool Execution
        Agent->>Tools: get_stock_price("NVDA")
        Tools->>External APIs: Fetch from yfinance
        External APIs-->>Tools: Return data
        Tools-->>Agent: Structured response
        
        Agent->>Tools: get_stock_news("NVDA")
        Tools->>External APIs: Fetch news
        External APIs-->>Tools: News data
        Tools-->>Agent: News response
    end
    
    Agent->>Agent: Generate analysis
    Agent-->>FastAPI: Streaming response
    FastAPI-->>Frontend: SSE stream
    Frontend-->>User: Display formatted analysis

✨ Features

🔍 Stock Analyzer

Real-time price snapshots and market cap
1-year historical price charts
Balance sheet and key financial metrics
Company facts and sector information
7-day news feed with source citations
Multi-dimensional analysis (Growth, Profitability, Valuation, Risk)

📈 Market Pulse

Watchlist monitoring with price snapshots
Top movers identification by sector
Macro headlines and market implications
Pre-market and intraday briefings
Sector performance visualization

⚔️ Stock Showdown

Side-by-side comparison of 2-4 tickers
Indexed returns analysis (1Y and 5Y)
Comparative metrics (valuation, growth, profitability)
Leverage and liquidity comparison
News and catalyst identification

🛡️ Compliance & Safety

Professional, neutral, data-driven tone
"Not financial advice" disclaimers
Source citations with publisher and date
Data limitation transparency
Follow-up questions to guide deeper analysis

🚀 Key Features & Optimizations

📦 Redis Caching

The backend implements intelligent caching with Redis to improve performance:

TTL-based cache: Different cache durations for different data types
- Stock prices: 60 seconds (real-time data)
- Historical prices: 12 hours (relatively stable)
- Balance sheets: 24 hours (updated quarterly)
- News: 1 hour (frequent updates)
Graceful degradation: Falls back to no cache if Redis is unavailable
Cache key generation: MD5-based hashing for efficient lookups

⚙️ TOML-based Configuration

System prompts are managed via prompt.toml for easy customization:

Structured prompt definitions with workflows
UI/UX specifications for each analysis type
Compliance rules and output formatting
Easy to modify without changing code

🎯 Flexible Data Granularity

Historical price queries support multiple frequency options:

Daily: Up to 90 days (for short-term analysis)
Weekly: Up to 52 weeks (for medium-term trends)
Monthly: Up to 60 months (~5 years, default)
Quarterly: Up to 40 quarters (~10 years, for long-term analysis)
Automatic data point limiting to optimize token usage

🛠️ Technology Stack

Backend

Framework: FastAPI
AI/ML: LangChain, LangGraph, LangSmith, OpenAI API
Data Sources: yfinance (market data), Tavily (web search)
Cache: Redis (optional, with TTL-based caching)
Configuration: TOML-based system prompts
Language: Python 3.10+
Package Manager: uv / pip

Frontend

Framework: React 19 + TypeScript
Build Tool: Vite
UI Library: GenUI SDK (@thesysai/genui-sdk)
Styling: Crayon UI, TailwindCSS, SASS
Linting: ESLint with TypeScript support

📋 Prerequisites

Node.js 18+ (for frontend)
Python 3.10+ (for backend)
OpenAI API Key or compatible LLM endpoint
Tavily API Key (for web search functionality)
Redis (optional, for caching - improves performance)

🚀 Setup & Installation

1. Clone the Repository

git clone https://github.com/andrecodea/nexus-financial-analyst.git
cd nexus-financial-analyst

2. Backend Setup

cd backend
# Create virtual environment
python -m venv .venv
# Activate virtual environment
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# OR using the project's pyproject.toml:
pip install .

3. Redis Setup (Optional but Recommended)

Redis caching improves performance by reducing API calls and speeding up responses. Linux/WSL:

sudo apt-get update
sudo apt-get install redis-server
sudo service redis-server start

macOS:

brew install redis
brew services start redis

Windows: Download from Redis for Windows or use WSL. Verify Redis is running:

redis-cli ping
# Should return: PONG

If Redis is not available, the backend will automatically fall back to operating without cache.

4. Environment Configuration

Create a .env file in the backend directory:

# Copy example environment file
cp ../.env.example backend/.env
# Edit backend/.env with your API keys

Required environment variables:

LLM_NAME=gpt-4o-mini                    # or your preferred model
LLM_BASE_URL=https://api.openai.com/v1  # OpenAI or compatible endpoint
OPENAI_API_KEY=your-openai-api-key-here
TAVILY_API_KEY=your-tavily-api-key-here

5. Frontend Setup

cd frontend
# Install dependencies
npm install
# Start development server
npm run dev

6. Run the Application

Terminal 1 - Backend:

cd backend
uvicorn main:app --reload --port 8000

Terminal 2 - Frontend:

cd frontend
npm run dev

Access the application at http://localhost:5173 (or the port shown by Vite)

🔧 Available Tools

The agent has access to these specialized tools:

Tool	Description	Parameters
`get_stock_price`	Real-time stock price	`ticker` (e.g., "NVDA")
`get_historical_stock_price`	Historical price data with flexible granularity	`ticker`, `start_date`, `end_date`, `frequency` (daily/weekly/monthly/quarterly, default: monthly)
`get_balance_sheet`	Company balance sheet	`ticker`
`get_stock_news`	Latest stock news	`ticker`
`web_search`	Web search via Tavily	`query`

📝 API Endpoints

POST `/api/chat`

Stream chat responses from the financial agent. Request Body:

{
  "message": "Analyze NVDA stock",
  "thread_id": "optional-session-id"
}

Response: Server-Sent Events (SSE) stream with agent responses

🐛 Troubleshooting

Backend Issues

Issue: ModuleNotFoundError: No module named 'langchain'

# Ensure virtual environment is activated
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -r requirements.txt

Issue: OpenAI API key not found

# Verify .env file exists in backend directory
# Check that OPENAI_API_KEY is set
cat backend/.env | grep OPENAI_API_KEY

Frontend Issues

Issue: Port already in use

# Change port in vite.config.ts or kill process on port 5173
# Linux/Mac:
lsof -ti:5173 | xargs kill -9
# Windows:
netstat -ano | findstr :5173
taskkill /PID <PID> /F

Issue: CORS errors

Ensure backend is running on port 8000
Check CORS middleware configuration in backend/main.py

🔒 Security Notes

⚠️ Important Security Information:

Never commit .env files or files containing secrets
The repository history was previously rewritten to remove exposed keys
You MUST rotate any API keys that may have been exposed

After history rewrite, collaborators should re-clone:

git clone https://github.com/andrecodea/nexus-financial-analyst.git

Use backend/.env.example as the template for environment variables
Add .env files to .gitignore (already configured)

📋 Security Resources:

See SECURITY.md for comprehensive security guidelines and best practices
See VALIDATION_REPORT.md for security validation results
Review the production deployment checklist before going live The project has been validated for data leaks and security vulnerabilities. See the validation report for details.

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow existing code style and conventions
Add tests for new features
Update documentation as needed
Ensure linting passes: npm run lint (frontend) / follow PEP 8 (backend)
Test thoroughly before submitting PR

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🙏 Acknowledgments

LangChain - Agent framework
LangSmith - LLM observability and debugging
yfinance - Market data
Tavily - Web search API
FastAPI - Backend framework
React - Frontend library
GenUI SDK - Chat interface

Disclaimer: This is not financial advice. This tool is for informational and educational purposes only. Always conduct your own research and consult with qualified financial advisors before making investment decisions.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

📊 Financial Research Agentic API

🎯 Overview of Nexus Financial Agent

🏗️ Architecture

🔄 Data Flow

✨ Features

🔍 Stock Analyzer

📈 Market Pulse

⚔️ Stock Showdown

🛡️ Compliance & Safety

🚀 Key Features & Optimizations

📦 Redis Caching

⚙️ TOML-based Configuration

🎯 Flexible Data Granularity

🛠️ Technology Stack

Backend

Frontend

📋 Prerequisites

🚀 Setup & Installation

1. Clone the Repository

2. Backend Setup

3. Redis Setup (Optional but Recommended)

4. Environment Configuration

5. Frontend Setup

6. Run the Application

🔧 Available Tools

📝 API Endpoints

POST `/api/chat`

🐛 Troubleshooting

Backend Issues

Frontend Issues

🔒 Security Notes

🤝 Contributing

Development Guidelines

📄 License

🙏 Acknowledgments

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

📊 Financial Research Agentic API

🎯 Overview of Nexus Financial Agent

🏗️ Architecture

🔄 Data Flow

✨ Features

🔍 Stock Analyzer

📈 Market Pulse

⚔️ Stock Showdown

🛡️ Compliance & Safety

🚀 Key Features & Optimizations

📦 Redis Caching

⚙️ TOML-based Configuration

🎯 Flexible Data Granularity

🛠️ Technology Stack

Backend

Frontend

📋 Prerequisites

🚀 Setup & Installation

1. Clone the Repository

2. Backend Setup

3. Redis Setup (Optional but Recommended)

4. Environment Configuration

5. Frontend Setup

6. Run the Application

🔧 Available Tools

📝 API Endpoints

POST /api/chat

🐛 Troubleshooting

Backend Issues

Frontend Issues

🔒 Security Notes

🤝 Contributing

Development Guidelines

📄 License

🙏 Acknowledgments

POST `/api/chat`