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

```bash
# 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