Financial Market Research Agent

A simplified, production-ready AI agent system for financial market research using OpenAI, Qdrant Cloud, and CrewAI with FastAPI endpoints.

🎯 Project Overview

This project demonstrates a practical implementation of an AI agent system with:

• OpenAI LLM Integration: Direct integration with GPT-4 for text generation and embeddings
• Qdrant Cloud Vector Database: Semantic search and RAG (Retrieval-Augmented Generation)
• CrewAI Agents: Multi-agent orchestration for financial research
• FastAPI REST API: Production-ready HTTP endpoints
• Comprehensive Testing Guide: Detailed instructions for testing all AI safety scenarios

📋 Features

Core Components

1. LLM Client (llm.py): OpenAI integration for text generation and embeddings
2. Vector Store (vector_db.py): Qdrant Cloud integration for semantic search
3. RAG System (rag.py): Retrieval-Augmented Generation for grounded responses
4. Agents (agents.py): CrewAI agents for market analysis, news research, and report writing
5. FastAPI App (main.py): REST API with 9 endpoints

API Endpoints

Endpoint	Method	Purpose
/health	GET	Health check
/rag/ingest	POST	Ingest documents into RAG system
/rag/search	POST	Semantic search in vector store
/rag/generate	POST	Generate response with RAG grounding
/rag/documents/{doc_id}	DELETE	Delete document from RAG
/llm/generate	POST	Generate text using OpenAI
/llm/embedding	POST	Generate embeddings
/research/workflow	POST	Run complete research workflow
/research/market-analysis	POST	Perform market analysis
/research/news	POST	Research news using RAG

🚀 Quick Start

Prerequisites

• Python 3.10+
• OpenAI API key (get one here)
• Qdrant Cloud account (create one here)

Installation

# Clone/extract project
cd finagent-simple

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

# Create .env file
cp .env.example .env

# Edit .env with your credentials
nano .env  # or use your preferred editor

Configuration

Edit .env with your credentials:

# OpenAI Configuration
OPENAI_API_KEY=sk-your-api-key-here
OPENAI_MODEL=gpt-4

# Qdrant Cloud Configuration
QDRANT_URL=https://your-instance.qdrant.io
QDRANT_API_KEY=your-qdrant-api-key

# FastAPI Configuration
API_HOST=0.0.0.0
API_PORT=8000
API_DEBUG=true

Run the Server

python main.py

Server will be available at http://localhost:8000

API Documentation: Visit http://localhost:8000/docs for interactive Swagger UI

📚 Usage Examples

1. Generate Text with OpenAI

curl -X POST "http://localhost:8000/llm/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Analyze the current tech sector",
    "system_prompt": "You are a financial analyst",
    "temperature": 0.7
  }'

2. Generate Embeddings

curl -X POST "http://localhost:8000/llm/embedding" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Apple stock analysis"
  }'

3. Ingest Documents for RAG

curl -X POST "http://localhost:8000/rag/ingest" \
  -H "Content-Type: application/json" \
  -d '{
    "doc_id": "apple_news_1",
    "content": "Apple Inc. announced record quarterly earnings with strong iPhone sales",
    "metadata": {"source": "news", "date": "2024-01-15"}
  }'

4. Search Documents

curl -X POST "http://localhost:8000/rag/search" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Apple earnings",
    "limit": 5
  }'

5. Generate with RAG Grounding

curl -X POST "http://localhost:8000/rag/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What were Apple'\''s latest earnings?"
  }'

6. Run Market Analysis

curl -X POST "http://localhost:8000/research/market-analysis" \
  -H "Content-Type: application/json" \
  -d '{
    "symbols": ["AAPL", "MSFT", "GOOGL"]
  }'

7. Research News

curl -X POST "http://localhost:8000/research/news" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest developments in AI stocks"
  }'

8. Run Complete Research Workflow

curl -X POST "http://localhost:8000/research/workflow" \
  -H "Content-Type: application/json" \
  -d '{
    "symbols": ["AAPL", "MSFT"],
    "query": "AI and machine learning investments"
  }'

🧪 Testing

This project includes comprehensive testing guides for all AI safety scenarios. See TESTING_GUIDE.md for detailed instructions on testing:

• Hallucinations: Verify factual accuracy and consistency
• Prompt Injection: Test resistance to adversarial prompts
• Data Drift: Monitor performance degradation over time
• Bias and Toxicity: Ensure fair and safe responses
• Performance: Measure latency and throughput
• Tool Use: Verify agent tool selection and planning
• Security: Test input validation and output sanitization
• RAG System: Verify document retrieval and grounding

Quick Test

# Run Python test suite
python test_api.py

📁 Project Structure

finagent-simple/
├── config.py              # Configuration management
├── llm.py                 # OpenAI integration
├── vector_db.py           # Qdrant Cloud integration
├── rag.py                 # RAG system
├── agents.py              # CrewAI agents
├── main.py                # FastAPI application
├── test_api.py            # Automated test suite
├── pyproject.toml         # Dependencies
├── .env.example           # Configuration template
├── README.md              # This file
└── TESTING_GUIDE.md       # Comprehensive testing guide

🔧 Architecture

System Flow

User Request
    ↓
FastAPI Endpoint
    ↓
┌─────────────────────────────────────┐
│  LLM Client (OpenAI)                │
│  - Text generation                  │
│  - Embedding generation             │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│  Vector Store (Qdrant Cloud)        │
│  - Document storage                 │
│  - Semantic search                  │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│  RAG System                         │
│  - Document ingestion               │
│  - Context retrieval                │
│  - Grounded generation              │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│  Agents (CrewAI)                    │
│  - Market Analyst                   │
│  - News Researcher                  │
│  - Report Writer                    │
└─────────────────────────────────────┘
    ↓
Response to User

Component Details

LLM Client: Wraps OpenAI API for text generation and embeddings

• Uses GPT-4 for generation
• Uses text-embedding-3-small for embeddings (1536 dimensions)

Vector Store: Manages Qdrant Cloud collections

• Stores documents with embeddings
• Performs semantic search with cosine similarity
• Supports metadata filtering

RAG System: Orchestrates retrieval and generation

• Ingests documents with embeddings
• Retrieves relevant context for queries
• Generates grounded responses

Agents: Multi-agent system for complex tasks

• Market Analyst: Analyzes market conditions
• News Researcher: Researches using RAG
• Report Writer: Synthesizes information into reports

🔐 Security Considerations

1. API Keys: Store in .env file, never commit to version control
2. Input Validation: All inputs are validated by Pydantic
3. Output Safety: LLM responses are returned as-is (implement sanitization if needed)
4. Rate Limiting: Implement at API gateway level for production
5. Authentication: Add authentication layer for production deployment

📊 Performance Characteristics

Operation	Typical Latency	Notes
Text Generation	2-10s	Depends on prompt length and complexity
Embedding Generation	1-3s	For typical financial text
Vector Search	<1s	Qdrant Cloud is very fast
RAG Generation	2-10s	Retrieval + generation time
Market Analysis	5-15s	Multiple LLM calls
Full Workflow	10-30s	All agents + synthesis

🚨 Troubleshooting

Issue: "Invalid API key" Error

Solution:

1. Check .env file has correct keys
2. Verify OpenAI API key is active
3. Verify Qdrant Cloud credentials

Issue: "Connection refused" to Qdrant

Solution:

1. Verify Qdrant Cloud instance is running
2. Check QDRANT_URL is correct (should be HTTPS)
3. Verify network connectivity

Issue: Slow Response Times

Solution:

1. This is normal for LLM calls (2-10 seconds)
2. Check OpenAI API rate limits
3. Verify network connectivity

Issue: "Collection not found" Error

Solution:

1. Ensure collection is created before ingesting documents
2. Check collection name matches in code
3. Verify Qdrant Cloud connection

📖 Learning Resources

• OpenAI API Documentation
• Qdrant Documentation
• CrewAI Documentation
• FastAPI Documentation

🧬 Testing All AI Scenarios

The TESTING_GUIDE.md file provides comprehensive instructions for testing:

1. Hallucination Testing: Verify consistency and factual accuracy
2. Prompt Injection Testing: Test resistance to adversarial inputs
3. Data Drift Testing: Monitor performance over time
4. Bias Testing: Ensure fair treatment across different inputs
5. Performance Testing: Measure latency and throughput
6. Security Testing: Verify input/output validation
7. RAG Testing: Verify document retrieval and grounding

Each test includes:

• Detailed explanation of what is being tested
• Curl commands to execute the test
• Expected behavior
• Interpretation of results

📝 Example: Testing Hallucinations

# Test 1: Consistency
for i in {1..3}; do
  curl -X POST "http://localhost:8000/llm/generate" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "What is 2 + 2?",
      "temperature": 0.0
    }' | jq '.response'
done

# All responses should be identical

🤝 Contributing

To extend this project:

1. Add new agents in agents.py
2. Add new endpoints in main.py
3. Add corresponding tests in TESTING_GUIDE.md
4. Update documentation

📄 License

This project is provided as-is for educational and testing purposes.

🎓 Key Concepts

Retrieval-Augmented Generation (RAG)

RAG combines retrieval and generation to produce grounded, factual responses:

1. User query is converted to embedding
2. Semantically similar documents are retrieved
3. Retrieved documents provide context
4. LLM generates response based on context

This significantly reduces hallucinations.

Multi-Agent Systems

Multiple specialized agents work together:

• Market Analyst: Analyzes market conditions
• News Researcher: Researches using RAG
• Report Writer: Synthesizes findings

Each agent is specialized for its task, improving overall quality.

Vector Embeddings

Text is converted to high-dimensional vectors:

• Same meaning → similar vectors
• Different meaning → different vectors
• Enables semantic search (finding similar documents)

Semantic Search

Search based on meaning, not keywords:

• Query: "Apple earnings"
• Finds documents about Apple's financial results
• Even if exact keywords don't match

📞 Support

For issues or questions:

1. Check TESTING_GUIDE.md for testing instructions
2. Review error messages carefully
3. Check API documentation
4. Verify configuration in .env

---

Ready to test AI agents? Start with the TESTING_GUIDE.md file! 🚀