CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

CrewAI-based multi-agent cryptocurrency analysis system with a Gradio web interface. Six specialized AI agents execute sequentially to fetch live market data, analyze historical trends, assess news sentiment, compute composite analytics, formulate trading strategy, and generate a narrative Markdown report.

Commands

# Setup
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Run locally (launches Gradio on 0.0.0.0:7860)
python app.py

No test suite or linter is configured. Testing is manual via the Gradio UI.

Required Environment Variables

Set these before running (or use a .env file):

• OPENAI_API_KEY — GPT-4 access for LLM agents and sentiment analysis
• SERPER_API_KEY — Serper search API for fetching crypto news
• COINGECKO_API_KEY — CoinGecko market data (optional but recommended)

Architecture

Entry point: app.py — defines all agents, tasks, the CrewAI Crew, and the Gradio UI.

Agent Pipeline (sequential execution via CrewAI)

User Input (crypto name, currency, lookback days)
  → Market Agent (gpt-4o-mini) + MarketDataTool     → live price, 24h volume
  → Historical Agent (gpt-4o-mini) + HistoricalDataTool → price history, % change, volatility, trend
  → Sentiment Agent (gpt-4.1) + SentimentTool       → news headlines, sentiment score, confidence
  → Analytics Agent (gpt-4o-mini) + AnalyticsTool    → composite score, alignment, effective sentiment
  → Strategy Agent (gpt-4.1)                         → trading bias, risk guidance
  → Reporting Agent (gpt-4.1)                        → final Markdown report (narrative prose, no bullets)

Tools (tools/)

Each tool extends CrewAI's BaseTool and returns a structured JSON dict:

Tool	File	External API	Key Behavior
MarketDataTool	market_data.py	CoinGecko /simple/price	Fetches live price + 24h volume
HistoricalDataTool	historical_data_tool.py	CoinGecko /market_chart	Computes % change, volatility (stdev of daily returns), trend classification
SentimentTool	sentiment_tool.py	Serper + OpenAI GPT-4.1	Fetches ~12 headlines, analyzes sentiment with LLM, validates/bounds scores
AnalyticsTool	analytics_tool.py	None (aggregation)	Composite score = (pct_change/10) + (effective_sentiment*1.5) - (volatility/100), bounded [-1,1]

Data Flow

Each tool returns a dict that downstream agents consume. The Analytics Agent aggregates all three data sources (market, historical, sentiment) into a single scored assessment. The Strategy and Reporting agents have no dedicated tools — they reason over prior agent outputs.

Deployment

Supports HuggingFace Spaces (Gradio SDK). Set API keys as Space secrets. The README.md contains the HuggingFace Spaces metadata card.

Key Patterns

• All tools use 10-second HTTP timeouts and return error dicts on failure
• Sentiment tool has multi-layer fallbacks: graceful neutral defaults if API keys missing, JSON extraction with substring fallback, bounds validation on all scores
• LLM model selection is hardcoded per agent in app.py (mix of gpt-4o-mini for data tasks, gpt-4.1 for reasoning tasks)
• The generate_report() function in app.py is the Gradio callback that instantiates and kicks off the Crew