FactFlow - Financial Market Sentiment-Reality Check Agent

FactFlow is a multi-agent system that compares news sentiment with actual market price action to identify market inefficiencies. It protects users from "Fake News" dumps and "Hollow Hype" pumps by providing data-driven market analysis.

🎯 Project Overview

Problem

Crypto and stock markets are plagued by emotional over-reactions. A scary headline can crash a price -5% even if the on-chain fundamentals haven't changed. Conversely, "hype" can pump a coin with zero volume support.

Solution

FactFlow acts as a rational referee. It reads the news using Google Search and cross-references it with hard market data from APIs to identify divergences between sentiment and reality.

Value Proposition

• Bullish Divergence Detection: When news is negative but price is stable (market ignoring bad news = strong holder confidence)
• Bearish Divergence Detection: When news is positive but price is dropping (weak fundamentals or selling pressure)
• Data-Driven Recommendations: Clear BUY/SELL/HOLD/ACCUMULATE signals based on divergence analysis

🏗️ Architecture

FactFlow uses a Sequential Multi-Agent System with three specialized agents:

1. News Scout Agent - Analyzes news sentiment using Google Search
2. Market Analyst Agent - Fetches real-time market data (price, volume, market cap)
3. Judge Agent - Synthesizes findings and provides recommendations

User Query → News Scout → Market Analyst → Judge → Final Recommendation

🚀 Quick Start

Prerequisites

• Python 3.11+
• Gemini API key from Google AI Studio

Installation

1. Clone the repository:

git clone <repository-url>
cd factflow

2. Install dependencies:

pip install -r requirements.txt

3. Set up environment variables:

cp env_template.txt .env
# Edit .env and add your GEMINI_API_KEY

4. Run the agent:

python -m factflow.main "Assess Ethereum right now"

Or use the interactive mode:

python -m factflow.main

📚 Documentation

• SETUP.md - Detailed setup instructions
• USAGE.md - Usage guide and examples

🎓 Course Concepts Demonstrated

This project demonstrates the following concepts from the 5-Day AI Agents Intensive Course:

✅ Multi-agent System: SequentialAgent pattern with 3 specialized agents
✅ Tools: Google Search (built-in), Custom Function Tools (market data APIs)
✅ Sessions & Memory: InMemorySessionService, Memory Bank for long-term storage
✅ Observability: Logging, Tracing, Metrics collection
✅ Agent Evaluation: LLM-as-a-Judge evaluation framework
✅ Deployment: Vertex AI Agent Engine deployment configuration

📁 Project Structure

factflow/
├── agents/              # Agent definitions
│   ├── __init__.py
│   └── sentiment_agents.py
├── tools/               # Custom function tools
│   ├── __init__.py
│   ├── market_tools.py
│   └── api_clients.py
├── session/             # Session & memory management
│   ├── __init__.py
│   ├── session_manager.py
│   └── memory_service.py
├── observability/       # Logging, tracing, metrics
│   ├── __init__.py
│   ├── logging_config.py
│   ├── tracing.py
│   └── metrics.py
├── evaluation/          # Agent evaluation framework
│   ├── __init__.py
│   ├── evaluator.py
│   └── test_cases.py
├── deployment/          # Deployment configurations
│   ├── __init__.py
│   └── deploy.py
├── docs/                # Documentation
│   ├── SETUP.md
│   └── USAGE.md
├── notebooks/           # Demo notebooks
│   └── factflow_demo.ipynb
├── media/               # Project images and diagrams
│   ├── thumbnail.png
│   ├── architecture-diagram.png
│   ├── feature-showcase.png
│   └── technology-stack.png
├── logs/                # Generated log files (created at runtime)
│   ├── factflow.log
│   ├── metrics.json
│   └── traces.json
├── main.py              # Main entry point
├── Dockerfile           # Docker container configuration
├── requirements.txt     # Python dependencies
├── env_template.txt     # Environment variables template
└── __init__.py          # Package initialization

🔧 Key Features

• Multi-Agent Architecture: Sequential workflow with specialized agents
• Real-Time Market Data: Integration with CoinGecko and yfinance APIs
• News Sentiment Analysis: Google Search integration for latest news
• Divergence Detection: Identifies gaps between sentiment and price action
• Session Management: Stateful conversations with InMemorySessionService
• Long-Term Memory: Memory Bank for historical analysis storage
• Observability: Comprehensive logging, tracing, and metrics
• Evaluation Framework: LLM-as-a-Judge for quality assessment

📊 Example Usage

from factflow import create_factflow_agent, FactFlowSessionManager

# Create agent
agent = create_factflow_agent()

# Create session manager
session_manager = FactFlowSessionManager()

# Get runner for a session
runner = session_manager.get_runner(session_id="user123")

# Run query
response = await runner.run("Assess Ethereum right now")
print(response.text)

🧪 Testing

Run the evaluation framework:

python -m factflow.evaluation.evaluator

Or from the factflow directory:

cd factflow
python evaluation/evaluator.py

🐳 Docker Deployment

Build and run with Docker:

# Build the image
docker build -t factflow .

# Run with a query
docker run --env-file .env factflow "Assess Ethereum right now"

📝 License

This project is part of the 5-Day AI Agents Intensive Course with Google.

🙏 Acknowledgments

• Google ADK (Agent Development Kit)
• Gemini API
• CoinGecko API (free tier)
• yfinance library

📧 Contact

For questions or issues, please create an issue in the repository.